API YAML

Custom APIs allow you to create endpoints that can be called to retrieve or manipulate data.

Properties

type

[string] - Refers to the resource type and must be api (required)

openapi

[object] - OpenAPI specification for the API endpoint

• summary - [string] - A brief description of what the API endpoint does

• parameters - [array of object] - List of parameters that the API endpoint accepts

• request_schema - [object] - JSON schema for the request body (use nested YAML instead of a JSON string)

• response_schema - [object] - JSON schema for the response body (use nested YAML instead of a JSON string)

security

[object] - Defines security rules and access control policies for resources

• access - [oneOf] - Expression indicating if the user should be granted access to the dashboard. If not defined, it will resolve to false and the dashboard won't be accessible to anyone. Needs to be a valid SQL expression that evaluates to a boolean.

  • option 1 - [string] - SQL expression that evaluates to a boolean to determine access

  • option 2 - [boolean] - Direct boolean value to allow or deny access

• row_filter - [string] - SQL expression to filter the underlying model by. Can leverage templated user attributes to customize the filter for the requesting user. Needs to be a valid SQL expression that can be injected into a WHERE clause

• include - [array of object] - List of dimension or measure names to include in the dashboard. If include is defined all other dimensions and measures are excluded

  • if - [string] - Expression to decide if the column should be included or not. It can leverage templated user attributes. Needs to be a valid SQL expression that evaluates to a boolean (required)

  • names - [anyOf] - List of fields to include. Should match the name of one of the dashboard's dimensions or measures (required)

    • option 1 - [array of string] - List of specific field names to include

    • option 2 - [string] - Wildcard '*' to include all fields

• exclude - [array of object] - List of dimension or measure names to exclude from the dashboard. If exclude is defined all other dimensions and measures are included

  • if - [string] - Expression to decide if the column should be excluded or not. It can leverage templated user attributes. Needs to be a valid SQL expression that evaluates to a boolean (required)

  • names - [anyOf] - List of fields to exclude. Should match the name of one of the dashboard's dimensions or measures (required)

    • option 1 - [array of string] - List of specific field names to exclude

    • option 2 - [string] - Wildcard '*' to exclude all fields

• rules - [array of object] - List of detailed security rules that can be used to define complex access control policies

  • type - [string] - Type of security rule - access (overall access), field_access (field-level access), or row_filter (row-level filtering) (required)

  • action - [string] - Whether to allow or deny access for this rule

  • if - [string] - Conditional expression that determines when this rule applies. Must be a valid SQL expression that evaluates to a boolean

  • names - [array of string] - List of field names this rule applies to (for field_access type rules)

  • all - [boolean] - When true, applies the rule to all fields (for field_access type rules)

  • sql - [string] - SQL expression for row filtering (for row_filter type rules)

skip_nested_security

[boolean] - Flag to control security inheritance

One of Properties Options

• SQL Query
• Metrics View Query
• Custom API Call
• File Glob Query
• Resource Status Check
• Union

SQL Query

Executes a raw SQL query against the project's data models.

sql

[string] - Raw SQL query to run against existing models in the project. (required)

connector

[string] - specifies the connector to use when running SQL or glob queries.

type: api
sql: "SELECT * FROM table_name WHERE date >= '2024-01-01'"

Metrics View Query

Executes a SQL query that targets a defined metrics view.

metrics_sql

[string] - SQL query that targets a metrics view in the project (required)

type: api
metrics_sql: "SELECT * FROM user_metrics WHERE date >= '2024-01-01'"

Custom API Call

Calls a custom API defined in the project to compute data.

api

[string] - Name of a custom API defined in the project. (required)

args

[object] - Arguments to pass to the custom API.

type: api
api: "user_analytics_api"
args:
    start_date: "2024-01-01"
    limit: 10

File Glob Query

Uses a file-matching pattern (glob) to query data from a connector.

glob

[oneOf] - Simple path/glob pattern or path/glob patternwith advanced options . (required)

• option 1 - [string] - Glob pattern used to match files or directories in the object store.

• option 2 - [object] - Configuration for specifying a file path/glob pattern with advanced options.

  • connector - [string] - Specifies the object store connector to use (e.g. "s3", "gcs"). If not provided, it is inferred from the scheme of the path.

  • path - [string] - Glob pattern used to match files or directories in the object store. (required)

  • start - [string] - Defines the lower bound (inclusive) for partition filtering. Only partitions with paths greater than or equal to this value are considered.

  • end - [string] - Defines the upper bound (exclusive) for partition filtering. Only partitions with paths less than this value are considered.

  • last - [integer] - Sets a lower bound based on the Nth partition from the end of the lexicographically sorted, successfully processed partitions. Only partitions after this point are included.

  • partition - [string] - Controls how matched files are grouped: - "file" (default) : Each matched path is returned as a row. Use the glob pattern to match files or directories at the level you want (for example, file-level or directory-level). - "directory": This mode is deprecated. Instead, use "file" with a glob that directly matches the directory level you want. - "hive": groups files by directory and extracts Hive-style partition values from the path as columns.

  • rollup_files - [boolean] - If true, includes a "files" array listing all files in each partition. Only applicable when using "directory" or "hive" partitioning.

  • transform_sql - [string] - Optional DuckDB SQL query used to transform the results. The resolved data is available as a table referenced using {{ .table }}.

type: api
glob: "data/*.csv"

Resource Status Check

Uses the status of a resource as data.

resource_status

[object] - Based on resource status (required)

• where_error - [boolean] - Indicates whether the condition should trigger when the resource is in an error state.

type: api
resource_status:
    where_error: true

Union

Invokes multiple resolvers and returns the union of their results. Each entry in the list is a resolver definition (e.g. sql, glob, metrics_sql, api).

union

[array of object] - List of resolver definitions whose results are combined into a single result set. (required)

# Exampe for union resolvers
type: api
union:
    - connector: duckdb
      sql: SELECT 1
    - connector: clickhouse
      sql: SELECT 2