# YAML configs

SnowDDL config is a directory with YAML files describing desired state of objects in Snowflake. You may find a [sample config](https://github.com/littleK0i/SnowDDL/tree/master/snowddl/_config/sample01_01) in SnowDDL GitHub repository.

Fundamentally, there are two types of objects in Snowflake:

### Account-level objects

DATABASE, WAREHOUSE, ROLE, etc.

Account-level objects are normally described by single YAML file located in the root level of config directory.

For example, all warehouses are described in `/warehouse.yaml`.

### Schema-level objects

TABLE, VIEW, FUNCTION, etc.

Schema-level objects are normally described by one YAML file per object located in sub-directories representing database and schema where object is located, as well as an object type.

For example: `/test_db/test_schema/table/test_table.yaml`.

This object:

* belongs to database `TEST_DB`
* belongs to schema `TEST_DB.TEST_SCHEMA`
* it is a `TABLE`
* its name is `TEST_TABLE`

Some schema-level objects support overloading (FUNCTION, PROCEDURE). It means that you may have multiple objects of this type in the same schema and with the same name, but with different arguments. In this case you must include base data types of arguments in the name of YAML config file.

For example: `/test_db/test_schema/function/my_function(number,varchar).yaml`.

## Documentation structure

The following pages describe configuration format for each object type.

Every page starts with **config path**, followed by some **examples**, followed by detailed **schema description**, followed by **usage notes** and **links**.

Links always contain URL's to relevant Snowflake commands and to the code of specific YAML parser with JSON schema. You should be able to check all technical details using provided links.

Small number of properties are <mark style="background-color:red;">highlighted with red</mark>. Such properties are "required".

## Object identifiers in YAML configs

When you see data type `(ident)` in schema description, it means this is the name of another object. For example, when one table refers to another using FOREIGN KEY.

For account-level objects, column names, parameter names - use name "as is".

For schema-level objects you may use fully-qualified names (`<database>.<schema>.<name>`), but you may also use a short name (`<name>`). It means that ref object is located in the same schema as current object.

This is very handy when you need to move some objects from one schema to another. There is no need to maintain fully qualified references all the time.

## YAML format and data types

YAML format is a bit complicated. You may find some good external tutorials:

* <https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started>
* <https://blog.codemagic.io/what-you-can-do-with-yaml/>

YAML data types are important for SnowDDL parsers, especially for account, session, copy parameters.

```yaml
# Correct
use_cached_results: true        # this is bool
unsupported_ddl_action: fail    # this is string
week_start: 1                   # this is int

# Incorrect
use_cached_results: "true"      # this is now string
unsupported_ddl_action: false   # this is now bool
week_start: "1"                 # this is now string
```

Incorrect data type will cause DDL query to fail. SnowDDL does not store "correct" data types for each parameter to make sure it will be compatible with any future changes.

## Config files extensions

Since version 0.36.0 supports both YAML file extensions: `.yml` and `.yaml`.

If SnowDDL encounters two files with the same names, but different extensions, validation error will be raised.


---

# Agent Instructions: 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:

```
GET https://docs.snowddl.com/basic/yaml-configs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.