> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL-GPT Syntax

*Kinetica* provides support for generative AI via
[SQL-GPT](/content/sql-gpt/concepts).

*SQL-GPT context* management features accessible via SQL include:

* [CREATE CONTEXT](/content/sql/sqlgpt#sql-gpt-create-context)
* [ALTER CONTEXT](/content/sql/sqlgpt#sql-gpt-alter-context)
* [SHOW CONTEXT](/content/sql/sqlgpt#sql-gpt-show-context)
* [DESCRIBE CONTEXT](/content/sql/sqlgpt#sql-gpt-desc-context)
* [DROP CONTEXT](/content/sql/sqlgpt#sql-gpt-drop-context)

For *SQL-GPT context* permission management, see:

* [GRANT SQL-GPT Context Permission](/content/sql/security#sql-security-priv-mgmt-gpt-grant)
* [REVOKE SQL-GPT Context Permission](/content/sql/security#sql-security-priv-mgmt-gpt-revoke)

*SQL-GPT* query generation & execution features accessible via SQL include:

* [GENERATE SQL](/content/sql/sqlgpt#sql-gpt-generate-sql)
* [EXECUTE\_AI\_QUERY](/content/sql/sqlgpt#sql-gpt-execute)

<a id="sql-gpt-create-context" />

## CREATE CONTEXT

Creates a new [SQL-GPT context](/content/sql-gpt/concepts#sql-gpt-overview-context).
The *context* can contain one or more base tables, a set of sample
question/answer pairs, and a set of rules for the table to aid in generating
appropriate SQL. While the tables, samples, and rules clauses are all optional,
a *context* must contain at least one clause of any kind to be considered valid.

```sql title="CREATE CONTEXT Syntax" theme={null}
CREATE [OR REPLACE] [TEMP] CONTEXT [<schema name>.]<context name>
[<table definition clause>[,...],]
[<sample definition clause>,]
[<rule definition clause>]
[WITH OPTIONS (ttl = '<ttl value>'[,...])]
```

### Parameters

<AccordionGroup>
  <Accordion title="OR REPLACE" id="or-replace" defaultOpen>
    Any existing *context* reference with the same name will be dropped before creating this
    one
  </Accordion>

  <Accordion title="TEMP" id="temp" defaultOpen>
    The *context* will be a temporary one; which means it will not be persisted (if the
    database is restarted, the *context* will be removed) and, if not continually accessed
    within the specified *TTL*, will be removed.
  </Accordion>

  <Accordion title="<schema name>" id="<schema-name>" defaultOpen>
    Name of the [schema](/content/sql/ddl#sql-create-schema) containing the *context*
  </Accordion>

  <Accordion title="<context name>" id="<context-name>" defaultOpen>
    Name of the *context*
  </Accordion>

  <Accordion title="<table definition clause>" id="<table-definition-clause>" defaultOpen>
    Optional clause containing the definitions of all tables to be used within the *context*
  </Accordion>

  <Accordion title="<sample definition clause>" id="<sample-definition-clause>" defaultOpen>
    Optional clause containing sample question/answer pairs that can help *SQL-GPT*
    understand the relationships between natural language and the tables within the *context*
  </Accordion>

  <Accordion title="<rule definition clause>" id="<rule-definition-clause>" defaultOpen>
    Optional clause containing global rules *SQL-GPT* should take into account when generating
    SQL from the tables within the *context*
  </Accordion>

  <Accordion title="WITH OPTIONS" id="with-options" defaultOpen>
    Optional indicator that a comma-delimited list of option/value assignments will follow.
    The following options are available:

    <div>
      <table class="table w-full [&_td]:min-w-[150px] [&_th]:text-left [&_td[data-numeric]]:tabular-nums">
        <thead>
          <tr>
            <th>Option</th>
            <th>Description</th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td><code>ttl</code></td>
            <td>Time-to-live, in minutes, for the *context*.  If the *context* is not accessed for this amount of time, it will be automatically removed from the database.  If <code>TEMP</code> is not specified, this option will be ignored.</td>
          </tr>
        </tbody>
      </table>
    </div>
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-create-context-table-def" />

### Table Definition Clause

The *table definition* clause provides information about a single table to
*SQL-GPT*.  All parameters are optional except for the table name.  The
*table definition* clause itself is also optional.

<Note>
  Kinetica will pass the all columns of the table to SQL-GPT
  regardless of whether they are named in the `COMMENTS` or `RULES`
  sections.  To avoid consuming unnecessary space in the *SQL-GPT context* with
  the unused columns, create a view with descriptive column names containing
  only the columns needed for generating SQL.
</Note>

```sql title="Table Definition Clause Syntax" theme={null}
(
    TABLE = [<schema name>.]<table name>
    [COMMENT = '<table comment>']
    [
        COMMENTS =
        (
            <column name> = '<column comment>',
            ...
            <column name> = '<column comment>'
        )
    ]
    [
        RULES =
        (
            '<table rule>',
            ...
            '<table rule>'
        )
    ]
)
```

#### Parameters

<AccordionGroup>
  <Accordion title="TABLE" id="table" defaultOpen>
    Specifier for the mandatory table definition table name
  </Accordion>

  <Accordion title="<schema name>" id="<schema-name>-2" defaultOpen>
    Name of the [schema](/content/sql/ddl#sql-create-schema) containing the table to include in the
    *context*
  </Accordion>

  <Accordion title="<table name>" id="<table-name>" defaultOpen>
    Name of the [table](/content/sql/ddl#sql-create-table) to include in the *context*
  </Accordion>

  <Accordion title="COMMENT" id="comment" defaultOpen>
    Specifier for an optional table comment
  </Accordion>

  <Accordion title="<table comment>" id="<table-comment>" defaultOpen>
    Note about the table that can give *SLQ-GPT* information about its use and the data it holds
  </Accordion>

  <Accordion title="COMMENTS" id="comments" defaultOpen>
    Specifier for an optional comma-separated list of column name & comment pairs
  </Accordion>

  <Accordion title="<column name>" id="<column-name>" defaultOpen>
    Name of a column in the given table
  </Accordion>

  <Accordion title="<column comment>" id="<column-comment>" defaultOpen>
    Note about the column that can give *SQL-GPT* information about its use and the specific data
    it holds
  </Accordion>

  <Accordion title="RULES" id="rules" defaultOpen>
    Specifier for an optional comma-separated list of rules for *SQL-GPT* to use in employing this
    table to generate SQL
  </Accordion>

  <Accordion title="<table rule>" id="<table-rule>" defaultOpen>
    Rule for *SQL-GPT* to use in employing this table to generate SQL; e.g., which columns should
    be considered (or not considered) when generating SQL using the table
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-create-context-sample-def" />

### Sample Definition Clause

A *sample definition* contains a set of question & answer pairs used to train
*SQL-GPT* for generating SQL.  Few (if any) samples should be required to
customize *SQL-GPT* for a use case.  The *sample definition* clause is optional.

<Note>
  A *sample definition* should reference tables that are included
  in *table definitions* within either its own *context* or a separate
  *context* that is passed along with it into a
  [GENERATE SQL](/content/sql/sqlgpt#sql-gpt-generate-sql) or [EXECUTE\_AI\_QUERY](/content/sql/sqlgpt#sql-gpt-execute)
  command.  This ensures that *SQL-GPT* has a proper definition (and
  understanding) of the tables and columns referenced in each sample query.
</Note>

```sql title="Sample Definition Clause Syntax" theme={null}
(
    SAMPLES =
    (
        '<question>' = '<SQL answer>',
        ...
        '<question>' = '<SQL answer>'
    )
)
```

#### Parameters

<AccordionGroup>
  <Accordion title="SAMPLES" id="samples" defaultOpen>
    *Sample definition* specifier keyword
  </Accordion>

  <Accordion title="<question>" id="<question>" defaultOpen>
    Natural-language question that will be answered by the corresponding `<SQL answer>` query
  </Accordion>

  <Accordion title="<SQL answer>" id="<sql-answer>" defaultOpen>
    SQL query that answers `<question>` using the tables contained within the *context*

    <Info>
      Quoted constants within the query will need to be escaped as per standard SQL
      convention; e.g., `'lamp'` in the following:

      ```
      'How many lamps?' = 'SELECT COUNT(*) FROM product WHERE type = ''lamp'';'
      ```
    </Info>
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-create-context-rule-def" />

### Rule Definition Clause

A *rule definition* contains a set of global rules that *SQL-GPT* should use in
employing the various tables named in the *context* to generate SQL.  By
convention, rules that apply to a specific table belong in the `RULES` section
of the [table definition](/content/sql-gpt/concepts#sql-gpt-overview-context-clause-table),
while rules that apply across tables or independently from any tables belong
here.  The *rule definition* clause is optional.

<Note>
  A *rule definition* should reference tables that are included
  in *table definitions* within either its own *context* or a separate
  *context* that is passed along with it into a
  [GENERATE SQL](/content/sql/sqlgpt#sql-gpt-generate-sql) or [EXECUTE\_AI\_QUERY](/content/sql/sqlgpt#sql-gpt-execute)
  command.  This ensures that *SQL-GPT* has a proper definition (and
  understanding) of any tables and columns referenced in each rule.
</Note>

```sql title="Rule Definition Clause Syntax" theme={null}
(
    RULES =
    (
        '<global rule>',
        ...
        '<global rule>'
    )
)
```

#### Parameters

<AccordionGroup>
  <Accordion title="RULES" id="rules-2" defaultOpen>
    Global *rule definition* specifier keyword
  </Accordion>

  <Accordion title="<global rule>" id="<global-rule>" defaultOpen>
    Global rule for *SQL-GPT* to use in employing multiple tables to generate SQL (joins, etc.) or
    when referencing database features that are independent of any table (functions, etc.)
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-create-context-example" />

#### Example

The following example creates a *SQL-GPT context* with the following criteria:

* Contains one table, `atc_current_position`, with:

  * a description
  * 4 column comments
  * 1 rule suggesting avoidance of one of the columns

* Contains one table, `atc_points`, with no extra definitions

* Contains one table, `airport_positions`, with:

  * a description
  * 2 column comments

* Contains 2 sample questions and their corresponding queries

* Contains 1 global rule suggesting how the `atc_current_position` &
  `atc_points` tables should be joined together

```sql CREATE CONTEXT Example theme={null}
CREATE CONTEXT example.atc_ctx
(
	TABLE = example.atc_current_position
	COMMENT = 'Current position of aircraft.'
	COMMENTS =
	(
		callsign = 'Aircraft callsign',
		ts = 'timestamp of most recent data point.',
		x = 'longitude position',
		y = 'latitude position'
	)
	RULES =
	(
		'Do not use the id column of the atc_current_position table'
	)
),
(
	TABLE = example.atc_points
),
(
	TABLE = example.airport_positions
	COMMENT = 'International airports and the centroid of their locations'
	COMMENTS =
	(
		airport_code = 'Name of airport',
		airport_centroid = 'Center of location of airport'
	)
),
(
	SAMPLES =
	(
		'What are the tracks for callsign UAL246?' =
		'
			SELECT ts, x, y
			FROM example.atc_points
			WHERE callsign = ''UAL246''
		',

		'What is the centroid of DCA airport?' =
		'
			SELECT airport_centroid
			FROM example.airport_positions
			WHERE airport_code = ''DCA''
		'
	)
),
(
	RULES =
	(
		'
			Use the ST_CONTAINS() function to join the airport_centroid column of the
			airport_positions table with the x and y columns of the atc_current_position table
		'
	)
)
```

<a id="sql-gpt-alter-context" />

## ALTER CONTEXT

Alters the configuration of a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).  Multiple *context*
entries can be added & removed in one command.  The general form is:

```sql title="ALTER CONTEXT Syntax" theme={null}
ALTER CONTEXT [<schema name>.]<context name>
[ADD | DROP] <context entry>,
...
[ADD | DROP] <context entry>
```

<a id="sql-gpt-alter-context-add-table" />

### Add Context Table

A *context table* can be added to a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="Add Context Table Syntax" theme={null}
ALTER CONTEXT [<schema name>.]<context name>
ADD <table definition clause>
```

See [Table Definition Clause](/content/sql/sqlgpt#sql-gpt-create-context-table-def) for syntax of the
`<table definition clause>`.

#### Examples

To add the `example.atc_country` table to the
`example.atc_ctx` *SQL-GPT context*:

```sql Add Context Table Example theme={null}
ALTER CONTEXT example.atc_ctx
ADD
(
	TABLE = example.atc_country
	COMMENT = 'Countries containing airports'
)
```

<a id="sql-gpt-alter-context-drop-table" />

### Drop Context Table

A *context table* can be removed from a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="Drop Context Table Syntax" theme={null}
ALTER CONTEXT [<context schema name>.]<context name>
DROP (TABLE = [<table schema name>.]<table name>)
```

#### Examples

To drop the `example.atc_country` table from the
`example.atc_ctx` *SQL-GPT context*:

```sql Drop Context Table Example theme={null}
ALTER CONTEXT example.atc_ctx
DROP (TABLE = example.atc_country)
```

<a id="sql-gpt-alter-context-add-sample" />

### Add Context Samples

*Context samples* can be added to a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context) that has not been
configured with any.  To add *samples* to a *context* already configured with
one or more, first [drop](/content/sql/sqlgpt#sql-gpt-alter-context-drop-sample) all
existing *samples*, and then add the new and any previous *samples* all at once.

```sql title="Add Context Samples Syntax" theme={null}
ALTER CONTEXT [<schema name>.]<context name>
ADD <sample definition clause>
```

See [Sample Definition Clause](/content/sql/sqlgpt#sql-gpt-create-context-sample-def) for syntax of the
`<sample definition clause>`.

#### Examples

To add a sample query for finding **JFK** airport's location to the
`example.atc_ctx` *SQL-GPT context*:

```sql Add Context Samples Example theme={null}
ALTER CONTEXT example.atc_ctx
ADD
(
	SAMPLES =
	(
		'What is the centroid of JFK airport?' =
		'
			SELECT airport_centroid
			FROM example.airport_positions
			WHERE airport_code = ''JFK''
		'
	)
)
```

<a id="sql-gpt-alter-context-drop-sample" />

### Drop Context Samples

*Context samples* can be removed from a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context) that has been configured
with one or more.

```sql title="Drop Context Samples Syntax" theme={null}
ALTER CONTEXT [<context schema name>.]<context name>
DROP (SAMPLES = ('' = ''))
```

#### Examples

To drop all *context samples* from the `example.atc_ctx` *SQL-GPT context*:

```sql Drop Context Samples Example theme={null}
ALTER CONTEXT example.atc_ctx
DROP (SAMPLES = ('' = ''))
```

<a id="sql-gpt-alter-context-add-rule" />

### Add Context Rules

*Context rules* can be added to a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context) that has not been
configured with any.  To add *rules* to a *context* already configured with one
or more, first [drop](/content/sql/sqlgpt#sql-gpt-alter-context-drop-rule) all
existing *rules*, and then add the new and any previous *rules* all at once.

```sql title="Add Context Rules Syntax" theme={null}
ALTER CONTEXT [<schema name>.]<context name>
ADD <rule definition clause>
```

See [Rule Definition Clause](/content/sql/sqlgpt#sql-gpt-create-context-rule-def) for syntax of the
`<rule definition clause>`.

#### Examples

To add a *rule* for joining the `example.airport_positions` table with the
`atc_current_position` table to the `example.atc_ctx` *SQL-GPT context*:

```sql Add Context Rules Example theme={null}
ALTER CONTEXT example.atc_ctx
ADD
(
	RULES =
	(
		'
			Use the ST_CONTAINS() function to join the airport_centroid column of the
			airport_positions table with the x and y columns of the atc_current_position table
		'
	)
)
```

<a id="sql-gpt-alter-context-drop-rule" />

### Drop Context Rules

*Context rules* can be removed from a
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context) that has been configured
with one or more.

```sql title="Drop Context Rules Syntax" theme={null}
ALTER CONTEXT [<context schema name>.]<context name>
DROP (RULES = (''))
```

#### Examples

To drop all *context rules* from the `example.atc_ctx` *SQL-GPT context*:

```sql Drop Context Rules Example theme={null}
ALTER CONTEXT example.atc_ctx
DROP (RULES = (''))
```

<a id="sql-gpt-drop-context" />

## DROP CONTEXT

Removes an existing [SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="DROP CONTEXT Syntax" theme={null}
DROP CONTEXT [<schema name>.]<context name>
```

### Examples

To remove the `example.atc_ctx` *SQL-GPT context*:

```sql DROP CONTEXT Example theme={null}
DROP CONTEXT example.atc_ctx
```

<a id="sql-gpt-show-context" />

## SHOW CONTEXT

Outputs the DDL statement required to reconstruct the given
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="SHOW CONTEXT Syntax" theme={null}
SHOW CONTEXT < [<schema name>.]<context name> | * >
```

<Info>
  The response to `SHOW CONTEXT` is a single-column result set
  with the DDL statement as the value in the `CONTEXT_DEFINITION` column.
</Info>

### Parameters

<AccordionGroup>
  <Accordion title="<schema name>" id="<schema-name>-3" defaultOpen>
    Name of the *schema* containing the *SQL-GPT context* to show
  </Accordion>

  <Accordion title="<context name>" id="<context-name>-2" defaultOpen>
    Name of the existing *SQL-GPT context* for which the DDL will be output; use `*` instead of
    *schema*/*context* name to output the DDL of all *contexts*
  </Accordion>
</AccordionGroup>

### Examples

To output the DDL for a *SQL-GPT context*, `example.atc_ctx`:

```sql SHOW CONTEXT Example theme={null}
SHOW CONTEXT example.atc_ctx
```

To output the DDL for all *SQL-GPT contexts*:

```sql SHOW CONTEXT (All Contexts) Example theme={null}
SHOW CONTEXT *
```

<a id="sql-gpt-desc-context" />

## DESCRIBE CONTEXT

Outputs the configuration of an existing
[SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="DESCRIBE CONTEXT Syntax" theme={null}
DESC[RIBE] CONTEXT < [<schema name>.]<context name> | * >
```

### Parameters

<AccordionGroup>
  <Accordion title="<schema name>" id="<schema-name>-4" defaultOpen>
    Name of the *schema* containing the *SQL-GPT context* to describe
  </Accordion>

  <Accordion title="<context name>" id="<context-name>-3" defaultOpen>
    Name of the existing *SQL-GPT context* for which the configuration will be output; use `*`
    instead of *schema*/*context* name to output the configuration of all *contexts*
  </Accordion>
</AccordionGroup>

### Response

The response to `DESCRIBE CONTEXT` is a seven-column result set:

| Output Column        | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| `CONTEXT_NAME`       | Name of the *SQL-GPT context*                                     |
| `OBJECT_TYPE`        | Type of the *context entity* being described within the *context* |
| `OBJECT_NAME`        | For a table entity type, the name of the table                    |
| `OBJECT_DESCRIPTION` | For a table entity type, the table comment                        |
| `OBJECT_RULES`       | For a table entity type, rules associated with the table          |
| `OBJECT_COMMENTS`    | For a table entity type, the table's column comments              |
| `OBJECT_SAMPLES`     | For a samples entity type, the list of question/answer pairs      |

### Examples

To show the configuration for a *SQL-GPT context*, `example.atc_ctx`:

```sql DESCRIBE CONTEXT Example theme={null}
DESC CONTEXT example.atc_ctx
```

To show the configuration for all *SQL-GPT contexts*:

```sql DESCRIBE CONTEXT (All Contexts) Example theme={null}
DESC CONTEXT *
```

<a id="sql-gpt-generate-sql" />

## GENERATE SQL

Creates a SQL query equivalent of the given natural-language question using the
specified [SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="GENERATE SQL Syntax" theme={null}
GENERATE SQL FOR '<question>'
[WITH OPTIONS (<option name> = '<option value>'[,...])]
```

### Parameters

<AccordionGroup>
  <Accordion title="<question>" id="<question>-2" defaultOpen>
    Natural-language question for which an equivalent SQL query will be generated
  </Accordion>

  <Accordion title="<schema name>" id="<schema-name>-5" defaultOpen>
    Name of the [schema](/content/sql/ddl#sql-create-schema) containing the *context* to use in generating
    the query
  </Accordion>

  <Accordion title="WITH OPTIONS" id="with-options-2" defaultOpen>
    Optional indicator that a comma-delimited list of SQL generation option/value assignments will
    follow.

    See [SQL Generation Options](/content/sql/sqlgpt#sql-gpt-generate-sql-opts) for the complete list of options.
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-generate-sql-opts" />

### SQL Generation Options

The following options can be specified to modify the way SQL queries are
generated.

<AccordionGroup>
  <Accordion title="ai_api_provider" id="ai_api_provider" defaultOpen>
    Name of an LLM service to use other than the default one; the default, `sqlgpt`, uses the
    Kinetica SQLGPT.io service.
  </Accordion>

  <Accordion title="ai_api_url" id="ai_api_url" defaultOpen>
    URL of an LLM service to use other than the default one.
  </Accordion>

  <Accordion title="context_name" id="context_name" defaultOpen>
    Name of the *SQL-GPT context* to use as a basis for generating SQL queries; should be of the
    form `[<schema name>.]<context name>`.
  </Accordion>

  <Accordion title="context_names" id="context_names" defaultOpen>
    Comma-separated list of names of *SQL-GPT contexts* to use as a basis for generating SQL
    queries; each should be of the form `[<schema name>.]<context name>`, and the entire list
    should be single-quoted.

    For example:

    ```
    context_names = 'example.atc_ctx,example.nyctaxi'
    ```
  </Accordion>

  <Accordion title="use_rag" id="use_rag" defaultOpen>
    Whether to use [retrieval-augmented generation (RAG)](/content/sql-gpt/concepts#sql-gpt-overview-rag) facilities
    with the given *SQL-GPT contexts* when processing this request.
  </Accordion>
</AccordionGroup>

### SQL Generation Examples

To generate the SQL equivalent query to a given question using the
`example.atc_ctx` *SQL-GPT context*:

```sql GENERATE SQL Example theme={null}
GENERATE SQL FOR
	'What is the callsign and position of the aircraft with most recent timestamp?'
WITH OPTIONS (context_name = 'example.atc_ctx')
```

To generate the SQL equivalent query to a given question using the
`nyctaxi_ctx` & `flights_ctx` *SQL-GPT contexts* with SQL RAG:

```sql GENERATE SQL with RAG Example theme={null}
GENERATE SQL FOR
	'What was the busiest airport, including taxis and flights, during January and February of 2023?'
WITH OPTIONS (context_names = 'nyctaxi_ctx, flights_ctx', use_rag = 'true')
```

<a id="sql-gpt-generate-tokens" />

## GENERATE TOKENS

Counts the number of tokens that would be used in generating the SQL in an
equivalent [GENERATE SQL](/content/sql/sqlgpt#sql-gpt-generate-sql) call.  This is, effectively, the
number of combined tokens in the given contexts, taking into account whether
[RAG](/content/sql-gpt/concepts#sql-gpt-overview-rag) is being used.

```sql title="GENERATE TOKENS Syntax" theme={null}
GENERATE TOKENS
[WITH OPTIONS (<option name> = '<option value>'[,...])]
```

### Parameters

<AccordionGroup>
  <Accordion title="<question>" id="<question>-3" defaultOpen>
    Natural-language question for which an equivalent SQL query will be generated
  </Accordion>

  <Accordion title="<schema name>" id="<schema-name>-6" defaultOpen>
    Name of the [schema](/content/sql/ddl#sql-create-schema) containing the *context* to use in generating
    the query
  </Accordion>

  <Accordion title="WITH OPTIONS" id="with-options-3" defaultOpen>
    Optional indicator that a comma-delimited list of SQL generation option/value assignments will
    follow.

    See [SQL Token Generation Options](/content/sql/sqlgpt#sql-gpt-generate-tokens-opts) for the complete list of options.
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-generate-tokens-opts" />

### SQL Token Generation Options

The following options can be specified to modify the way the counted tokens are
generated.

<AccordionGroup>
  <Accordion title="context_name" id="context_name-2" defaultOpen>
    Name of the *SQL-GPT context* to use as a basis for counting generated tokens; should be of the
    form `[<schema name>.]<context name>`.
  </Accordion>

  <Accordion title="context_names" id="context_names-2" defaultOpen>
    Comma-separated list of names of *SQL-GPT contexts* to use as the basis for counting generated
    tokens; each should be of the form `[<schema name>.]<context name>`, and the entire list
    should be single-quoted.

    For example:

    ```
    context_names = 'example.atc_ctx,example.nyctaxi'
    ```
  </Accordion>

  <Accordion title="use_rag" id="use_rag-2" defaultOpen>
    Whether to use [retrieval-augmented generation (RAG)](/content/sql-gpt/concepts#sql-gpt-overview-rag) facilities
    with the given *SQL-GPT contexts* when processing this request.
  </Accordion>
</AccordionGroup>

### SQL Token Generation Examples

To count the generated tokens for the `example.atc_ctx`
*SQL-GPT context*:

```sql GENERATE TOKENS Example theme={null}
GENERATE TOKENS
WITH OPTIONS (context_name = 'example.atc_ctx')
```

To count the generated tokens for the `nyctaxi_ctx` & `flights_ctx`
*SQL-GPT contexts* with SQL RAG:

```sql GENERATE TOKENS with RAG Example theme={null}
GENERATE TOKENS
WITH OPTIONS (context_names = 'nyctaxi_ctx, flights_ctx', use_rag = 'true')
```

<a id="sql-gpt-execute" />

## EXECUTE\_AI\_QUERY

Executes a SQL query equivalent of the given natural-language question using the
specified [SQL-GPT context](/content/sql/sqlgpt#sql-gpt-create-context).

```sql title="EXECUTE_AI_QUERY Table Function Syntax" theme={null}
SELECT *
FROM TABLE
(
    EXECUTE_AI_QUERY
    (
        QUESTION => '<question>',
        OPTIONS => KV_PAIRS (<option name> = '<option value>'[,...])
    )
)
```

### Parameters

<AccordionGroup>
  <Accordion title="<question>" id="<question>-4" defaultOpen>
    Natural-language question for which an equivalent SQL query will be executed
  </Accordion>

  <Accordion title="<schema name>" id="<schema-name>-7" defaultOpen>
    Name of the [schema](/content/sql/ddl#sql-create-schema) containing the *context* to use in generating
    the query
  </Accordion>

  <Accordion title="OPTIONS" id="options" defaultOpen>
    [SQL generation options](/content/sql/sqlgpt#sql-gpt-execute-opts), specified as a set of key/value pairs
    passed as a comma-delimited list of `<key> = '<value>'` assignments to the `KV_PAIRS`
    function; e.g.:

    ```
    KV_PAIRS(context_name = 'atc_ctx')
    ```
  </Accordion>
</AccordionGroup>

<a id="sql-gpt-execute-opts" />

### SQL Generation Options

The following options can be specified to modify the way the executed SQL query
is generated.

<AccordionGroup>
  <Accordion title="ai_api_provider" id="ai_api_provider-2" defaultOpen>
    Name of an LLM service to use other than the default one; the default, `sqlgpt`, uses the
    Kinetica SQLGPT.io service.
  </Accordion>

  <Accordion title="ai_api_url" id="ai_api_url-2" defaultOpen>
    URL of an LLM service to use other than the default one.
  </Accordion>

  <Accordion title="context_name" id="context_name-3" defaultOpen>
    Name of the *SQL-GPT context* to use in generating the executed query; should be of the form
    `[<schema name>.]<context name>`.
  </Accordion>

  <Accordion title="context_names" id="context_names-3" defaultOpen>
    Comma-separated list of names of *SQL-GPT contexts* to use in generating the executed query;
    each should be of the form `[<schema name>.]<context name>`, and the entire list should be
    single-quoted.

    For example:

    ```
    context_names = 'example.atc_ctx,example.nyctaxi'
    ```
  </Accordion>

  <Accordion title="use_rag" id="use_rag-3" defaultOpen>
    Whether to use [retrieval-augmented generation (RAG)](/content/sql-gpt/concepts#sql-gpt-overview-rag) facilities
    with the given *SQL-GPT contexts* when processing this request.
  </Accordion>
</AccordionGroup>

### SQL Execution Examples

To execute the SQL equivalent query to a given question using the
`example.atc_ctx` *SQL-GPT context*:

```sql EXECUTE_AI_QUERY Example theme={null}
SELECT *
FROM TABLE
(
	EXECUTE_AI_QUERY
	(
		QUESTION => 'What is the callsign and position of the aircraft with most recent timestamp?',
		OPTIONS => KV_PAIRS (context_name = 'example.atc_ctx')
	)
)
```

To execute the SQL equivalent query to a given question using the
`nyctaxi_ctx` & `flights_ctx` *SQL-GPT contexts* with SQL RAG:

```sql EXECUTE_AI_QUERY with RAG Example theme={null}
SELECT *
FROM TABLE
(
	EXECUTE_AI_QUERY
	(
		QUESTION => 'What was the busiest airport, including taxis and flights, during January and February of 2023?',
		OPTIONS => KV_PAIRS (context_names = 'nyctaxi_ctx, flights_ctx', use_rag = 'true')
	)
)
```