> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/build/stage-2-productize/define-models-and-logic/data-models/properties.md). # Properties The `MODEL` block is the DDL section of every Vulcan model file. Properties declared here control the model's name, materialization strategy, schedule, documentation, and data quality rules. They override any defaults set in `modelDefaults` inside `config.yaml`. *** ## Quick reference | Property | Type | Required | Description | | --------------------- | --------------- | :------: | ------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Fully-qualified model name: `schema.table` or `catalog.schema.table`. | | `kind` | string or dict | No | Materialization strategy. Default: `VIEW`. See [Model kinds](/concepts/resources/vulcan/components/model/model_kinds.md). | | `cron` | string | No | Schedule expression for automatic runs (e.g. `@daily`, `*/15 * * * *`). | | `cron_tz` | string | No | Timezone for the cron schedule. Applies to when the model runs, not the data intervals. | | `start` | string | No | Earliest date to process. Accepts ISO dates (`'2025-01-01'`) or relative expressions (`'1 year ago'`). | | `end` | string | No | Latest date to process. Same format as `start`. | | `interval_unit` | string | No | Temporal granularity of data intervals: `day`, `hour`, `half_hour`, etc. Defaults to cron granularity. | | `grains` | string or tuple | No | Columns that uniquely identify a row. Documents the primary key and enables assertion checking. | | `columns` | array | No | Explicit column names and types. Required for Python and SEED models. | | `column_descriptions` | dict | No | Column-level documentation registered as column comments in the warehouse. | | `column_tags` | dict | No | Tags per column for governance and discovery (e.g. `pii`, `primary_key`). | | `column_terms` | dict | No | Business glossary terms per column using dot notation (e.g. `customer.customer_id`). | | `description` | string | No | Model description. Registered as a table comment and appears in catalog search. | | `owner` | string | No | Person or team responsible for this model. Used for notifications and governance. | | `tags` | tuple | No | Labels for organizing and filtering models (e.g. `('gold', 'fact', 'revenue')`). | | `terms` | tuple | No | Business glossary references using dot notation (e.g. `'sales.daily_metrics'`). | | `assertions` | array | No | Data quality rules that run after every materialization and block the model if they fail. | | `depends_on` | array | No | Explicit model dependencies. Required for Python models; optional for SQL. | | `partitioned_by` | string or array | No | Partition key column(s) for engines that support table partitioning. | | `table_format` | string | No | Table format: `iceberg`, `hive`, or `delta`. For engines that support multiple formats. | | `storage_format` | string | No | Storage file format: `parquet` or `orc`. | | `dialect` | string | No | SQL dialect override for this model. Defaults to `modelDefaults.dialect`. | | `gateway` | string | No | Specific gateway to use for execution. For multi-warehouse setups. | | `stamp` | string | No | Arbitrary version string that forces a new model version. | | `ignored_rules` | string or array | No | Linter rules to skip for this model. Use `'ALL'` to skip all. | *** ## Essential properties ### name The model's name is how it is identified in the warehouse. Use the `schema.table` format. Vulcan creates a table with this name in the target schema. ```sql MODEL ( name silver.fct_daily_sales, ... ); ``` Include the catalog when the model targets a schema outside the gateway's default: ```sql MODEL ( name analytics_db.silver.fct_daily_sales, ... ); ``` In non-production environments, Vulcan automatically prefixes the schema (`silver__dev.fct_daily_sales`). Production always uses the name as written. *** ### kind Controls how the model materializes. This is the most important property for each model. ```sql MODEL ( name bronze.orders, kind FULL, ... ); ``` For incremental models, `kind` takes a nested block with kind-specific options: ```sql MODEL ( name silver.events, kind INCREMENTAL_BY_TIME_RANGE ( time_column event_ts ), ... ); ``` See [Model kinds](/concepts/resources/vulcan/components/model/model_kinds.md) for all strategies and when to use each. *** ### cron Sets the refresh schedule. Without a schedule, the model only runs when manually triggered. ```sql MODEL ( name silver.fct_daily_sales, cron '*/15 * * * *', -- every 15 minutes ... ); ``` Vulcan shortcuts: | Shortcut | Equivalent | | ---------- | ----------- | | `@hourly` | `0 * * * *` | | `@daily` | `0 0 * * *` | | `@weekly` | `0 0 * * 0` | | `@monthly` | `0 0 1 * *` | *** ### grains Declares the columns that uniquely identify each row. Functions as the model's primary key and is required for assertion checking on uniqueness. ```sql MODEL ( name silver.fct_daily_sales, grains [order_date, region_id, customer_id, product_id], ... ); ``` For a single-column key: ```sql grains [customer_id] ``` *** ### columns and column\_descriptions `columns` declares explicit column names and types. Required for Python and SEED models; optional for SQL models where Vulcan can infer types from the query. `column_descriptions` adds per-column documentation that Vulcan registers as column comments in the warehouse. ```sql MODEL ( name silver.fct_daily_sales, columns ( order_date TIMESTAMP, region_id INTEGER, total_revenue NUMERIC(15, 2) ), column_descriptions ( order_date = 'Order date at daily grain', total_revenue = 'Gross revenue from line items' ), ... ); ``` *** ### description, owner, tags, terms Documentation and governance properties that appear in catalog search and lineage tools. ```sql MODEL ( name gold.rfm_customer_segmentation, description 'RFM customer segmentation for retention and campaign prioritization.', owner 'analytics-team', tags ('gold', 'customer', 'rfm', 'segmentation'), terms ('customer.rfm_analysis', 'analytics.customer_segmentation'), ... ); ``` *** ### assertions Attaches data quality rules to the model. These run after every materialization and block the model if they fail. Built-in functions cover the most common checks: ```sql MODEL ( name bronze.orders, assertions ( unique_values(columns := (order_id)), not_null(columns := (order_id, customer_id, order_date, order_status)), accepted_values(column := order_status, is_in := ('Confirmed', 'Shipped', 'Cancelled')) ), ... ); ``` See [Assertions](/build/stage-2-productize/define-the-contract/assertions.md) for the full list of built-in functions and how to write custom SQL assertions. *** ### depends\_on Explicitly declares model dependencies. Vulcan infers dependencies from SQL `FROM` and `JOIN` clauses automatically. Use `depends_on` for Python models (which Vulcan cannot parse for dependencies) and for hidden dependencies that do not appear in the query text. ```sql MODEL ( name silver.summary, depends_on ['silver.fct_daily_sales', 'silver.dim_customer_profile'], ... ); ``` *** ## Storage properties These properties control physical storage and are only meaningful for engines that support them. | Property | Supported engines | Description | | --------------------- | --------------------------- | ---------------------------------------------------------------------------------- | | `partitioned_by` | Spark, Databricks, BigQuery | Column(s) to partition the table by. Enables partition pruning for faster queries. | | `table_format` | Spark, Trino | Table format: `iceberg`, `hive`, or `delta`. | | `storage_format` | Spark | Physical file format: `parquet` or `orc`. | | `physical_properties` | Engine-specific | Pass engine-specific table properties (e.g. retention policies, labels). | | `virtual_properties` | Engine-specific | Pass engine-specific view properties (e.g. Snowflake `SECURE` views). | | `session_properties` | Engine-specific | Session-level settings applied when the model executes (e.g. query timeouts). | *** ## Full reference The properties listed here cover what `orders-analytics` uses and the most common options. For advanced properties (`forward_only`, `on_destructive_change`, `batch_size`, `lookback`, SCD Type 2 options, and others), see [Properties](/concepts/resources/vulcan/components/model/properties.md) in the Vulcan under Concepts. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/build/stage-2-productize/define-models-and-logic/data-models/properties.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.