# Import Actian AI Analyst Format (YAML / JSON)

The Actian AI Analyst native format is the most complete import format. It supports all entity types with full field-level detail, ID-based matching for renames, and multi-file uploads.

Use this format for backups, migrations between Actian AI Analyst environments, or programmatic bulk updates.

***

### Supported File Types

* `.yaml` / `.yml`
* `.json`

Both formats use the same structure — only the serialization differs.

***

### File Structure

```yaml
version: "1.0"
exported_at: "2026-01-28T00:00:00Z"

models:
  - id: "model_xyz"
    name: "Orders"
    description: "All customer orders"
    agent_guidance: "Use this model for order-related questions"
    source:
      data_source_name: "PostgreSQL DB"
      type: "TABLE"           # TABLE, VIEW, or CUSTOM_QUERY
      path: ["public", "orders"]
      query: null              # Only for CUSTOM_QUERY
    grain:
      keys: ["id"]
      description: "One row per order"
    dimensions:
      - id: "dim_001"
        name: "Order ID"
        expression: "id"
        type: "number"
        description: "Unique order identifier"
        primary_key: true
        time_grains: []
        sample_values: ["1001", "1002", "1003"]
        enum_values: []
      - id: "dim_002"
        name: "Status"
        expression: "status"
        type: "string"
        description: "Current order status"
        primary_key: false
        enum_values:
          - value: "pending"
            description: "Awaiting processing"
            sort_order: 1
          - value: "shipped"
            description: "In transit"
            sort_order: 2
    measures:
      - id: "meas_001"
        name: "Total Amount"
        expression: "SUM(amount)"
        description: "Sum of order amounts"
        unit: "USD"
        precision: 2
    filters:
      - id: "filter_001"
        name: "Active Orders"
        expression: "status != 'cancelled'"
        description: "Excludes cancelled orders"
        apply_default: false

relationships:
  - id: "rel_001"
    name: "Orders to Customers"
    description: "Each order belongs to a customer"
    from_model: "Orders"
    from_key: "customer_id"
    to_model: "Customers"
    to_key: "id"
    type: "one_to_many"
    join_type: "left"

metrics:
  - id: "metric_001"
    name: "Total Revenue"
    description: "Sum of all order amounts"
    agent_guidance: "Use for revenue questions"
    expression: "SUM(amount)"
    anchor_model: "Orders"
    unit: "USD"
    precision: 2
    time_dimension:
      model: "Orders"
      dimension: "Order Date"
    time_grains: ["day", "month", "year"]
    group_by_dimensions:
      - model: "Orders"
        dimension: "Status"
    joins:
      - alias: "customer"
        from_key: "customer_id"
        to_model: "Customers"
        to_key: "id"
        join_type: "left"
    filters:
      - expression: "amount > 0"
        apply_default: true
    tags: ["revenue", "business"]

glossary:
  - id: "term_001"
    term: "Revenue"
    definition: "Total sales amount before deductions"
    synonyms: ["Income", "Sales"]
    tags: ["financial"]
    mappings:
      - type: "metric"
        name: "Total Revenue"
      - type: "model"
        name: "Orders"
      - type: "dimension"
        model: "Orders"
        name: "Amount"

agents:
  - id: "agent_001"
    name: "Sales Analyst"
    description: "Answers questions about sales performance"
    instructions: "Focus on revenue trends and customer segments"
    semantic_layer_access:
      models:
        - name: "Orders"
          dimensions: ["Order ID", "Status", "Order Date"]
          measures: ["Total Amount"]
          filters: ["Active Orders"]
      metrics: ["Total Revenue"]
      glossary:
        mode: "INCLUDE_TAGS"   # ALL, INCLUDE_TAGS, or EXCLUDE_TAGS
        tags: ["financial"]
```


---

# 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.wobby.ai/governance/import-semantic-layer-and-agents/import-wobby-format-yaml-json.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.