# Arrays & Nested Structures

## Object Arrays

**Definition:** Arrays containing objects (`ARRAY_TYPE = 'object'`).

**Characteristics:**

* Each array element is an object with its own attributes
* Separate Dynamic Table created for array contents
* Foreign key relationships link array table to parent
* Polymorphic version: `{attribute_name}_array_object` (e.g., `orders_array_object`)

**Code generation:**

* Root table contains array reference
* Array table named using `CREATE_OBJECT_NAME_ALIAS_NAME` or default `{root_table_name}_array_object`
* Foreign keys configured in Foreign Keys section

***

## Primitive Arrays

**Definition:** Arrays containing primitive values (`ARRAY_TYPE = 'primitive'`).

**Characteristics:**

* Array elements are simple values (not objects)
* Stored as VARIANT or ARRAY types in Snowflake
* May be flattened into separate table depending on configuration
* `ARRAY_PRIMITIVE_TYPE` specifies element data type (`'str'`, `'int'`, `'float'`, `'bool'`)
* Polymorphic version: `{attribute_name}_array_primitive` (e.g., `tags_array_primitive`)

***

## Polymorphic Arrays

**Definition:** Arrays containing both objects and primitives (`ARRAY_TYPE = 'primitive,object'`).

**Characteristics:**

* Both `array_primitive` and `array_object` polymorphic versions are activated
* Most complex array type; requires careful handling in transformations
* Transformation expressions may need type checking to handle both cases

**Example:**

```json
{
  "items": ["simple string", {"name": "object item", "value": 100}]
}
```

Both `items_array_primitive` and `items_array_object` are active.

***

## Nested Structures

**Nested objects:** Attributes nested at any depth create separate attributes at each level:

* `customer` (object, level 0)
* `customer.contact` (object, level 1)
* `customer.contact.email` (string, level 2)

**Nested arrays:** Arrays nested within arrays create indexed paths:

* `orders` (array)
* `orders[0].items` (array)
* `orders[0].items[0].product_id` (string)

**Mixed nesting:** Objects and arrays can be combined at any depth. Each level tracked via `ATTRIBUTE_LEVEL` and `PARENT_OBJECT`/`PARENT_ARRAY`.

***

## Array Configuration

**Foreign key relationships:** For object arrays, configure in Foreign Keys section:

* Links array table to parent table
* Specifies foreign key columns (`ATTRIBUTE_FOREIGN_KEY_COLUMNS`)
* Relationship type: `'many_to_one'` or `'one_to_one'` (`ARRAY_RELATIONSHIP_TYPE`)
* Join type: `'left_outer'` or `'inner'` (`ARRAY_RELATIONSHIP_JOIN_TYPE`)

**Array metadata fields:**

* `ARRAY_TYPE` - `'object'`, `'primitive'`, or `'primitive,object'`
* `ARRAY_PRIMITIVE_TYPE` - Element data type for primitive arrays
* `ARRAY_RELATIONSHIP_NAME` - Relationship name
* `ARRAY_RELATIONSHIP_DESCRIPTION` - Relationship description
* `INCLUDE_IN_CODE_GEN` - Controls array table generation


---

# 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.datapancake.com/core-concepts/attribute-metadata/arrays-and-nested-structures.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.