AI API

The AI API provides a standard interface for interacting with large language models (LLMs) as a turnkey solution for text-to-semantic layer queries.

Specifically, you can send the AI API a message (or conversation of messages) and it will return a Cube REST API query. Optionally, it will also run the query and return the results.

Configuration

While the AI API is in preview, your Cube account team will enable and configure it for you.

If you wish to enable or disable the AI API on a specific Cube deployment, you may do so by going to "Settings" in the Cube Cloud sidebar, then "Configuration", and then toggling the "AI API" configuration flag switch.

To find your AI API endpoint in Cube Cloud, go to the Overview page, click API credentials, and choose the AI API tab.

Getting Started

Data modeling

The AI API currently requires views in order to generate queries. This is because:

1. Views let you create carefully-curated datasets, resulting in better outputs from LLMs. That is, you can choose exactly what is "ready" for the AI to see and what is not.
2. Views define deterministic joins between Cubes, so the LLM does not have to "guess" at join ordering

To use the AI API, set up one or more views before getting started.

Authentication

Authentication works the same as for the REST API.

The API Token is passed via the Authorization Header. The token itself is a JSON Web Token (opens in a new tab), the Security section describes how to generate it.

Example request

Given the data model from the "data modeling" section above, you could send a request with the following body:

{
  "messages": [
    {
      "role": "user",
      "content": "Where do we have the highest aov this year?"
    }
  ]
}

Based on the view(s) provided, the AI API generates a Cube REST API request that could be used to answer the user's question. For example, you might receive the following response:

{
  "message": "To find where we have the highest Average Order Value (AOV) this year, we can analyze the data by comparing the AOV across different dimensions such as cities or states.",
  "cube_query": {
    "measures": ["orders_view.average_order_value"],
    "dimensions": ["orders_view.users_city"],
    "timeDimensions": [
      {
        "dimension": "orders_view.created_at",
        "dateRange": "this year"
      }
    ],
    "order": {
      "orders_view.average_order_value": "desc"
    },
    "limit": 10
  }
}

See running queries for details on how to run the Cube query generated.

Running queries

You have two possible ways to run the query:

1. runQuery parameter

Use the runQuery request parameter to have the AI API run the query and report results back. When doing this, the request above would become:

{
  "messages": [
    {
      "role": "user",
      "content": "Where do we have the highest aov this year?"
    }
  ],
  "runQuery": true
}

The response will be the same as above, followed by a second JSON object representing the response (see the REST API reference for its format).

2. /load

Alternatively, you may take the generated cube_query from the response and then call the REST API /load endpoint with it in the /load request body. This is recommended for advanced use-cases where you need more control over formatting, pagination, etc. or if you are adding the AI API to an existing Cube REST API implementation.

Error Handling

Occasionally you may encounter errors. There are a few common categories of errors:

1. Cannot answer question

If the AI API is unable to generate a query because the view(s) in your data model do not have the appropriate fields to answer the question, you will receive a message like the following, and no cube_query in the response:

{
    "message": "I'm sorry, but the current data modeling doesn't cover stock prices or specific company data like NVDA. I will notify the data engineering team about this request."
}

2. Invalid query

Occasionally, the AI API may generate a query that is invalid or cannot be run. When this happens, you will receive an error upon running the query.

One way of handling this is to pass the error message back into the AI API; it may then self-correct and provide a new, valid query.

3. Continue wait

When using "runQuery": true, you might sometimes receive a query result containing { "error": "Continue wait" }. If this happens, you should use /load (described above) instead of runQuery to run the query, and handle retries as described in the REST API documentation.