SQL Query

The Query module provides functions to generate, run, and manage SQL queries.

Query Generation and Update

This function allows you to generate or refine/update a query based on the provided request parameters.

public GeneratedQuery generate(QueryGenerationRequest params) throws IOException;

Parameters:

• params (required): An object containing the query generation request parameters.

  • searchContext (optional): An array of SearchContext objects that specify the database, schema, and table names to consider during query generation. The system will automatically pick the needed objects; if this field is omitted, all the objects in the database will be considered (that's the common case).
  • tweakHistory (optional): An array of Tweak objects that provide additional information for query generation. This is to interactively update a query. The Tweaks are the previous asks and response queries and these will be refined with the new ask.
  • ask (optional): A string containing the English language statement for the query generation. Can be a question or a description of the requested result.
  • uuid (optional): A unique identifier for the query.
  • dialect (optional): The dialect of the query: Snowflake or PostgreSQL.
  • parentUuid (optional): The parent query's unique identifier. This is for interactive sessions and refers to the UUID from the previous interaction.

Returns:

A GeneratedQuery object containing the details of the generated SQL query.

The GeneratedQuery object represents the details of a generated query and contains the following fields:

• uuid (optional): A string representing the unique identifier of the generated query. This can be later used for liking the query. Please refer to documentation of "Liking a Query".
• liked (optional): A boolean value indicating whether the query has been liked/favorited by the user. This is always false when the query is generated but can be set via the "like" API.
• tables (optional): An array of TableName objects representing the tables used in the generated query (this is a subset of the searchContext). Each TableName object may contain the following fields:
  • tableName (required): The name of the table.
  • schemaName (optional): The name of the schema (if applicable).
  • databaseName (optional): The name of the database (if applicable).
• semanticContext (optional): An array of SemanticStatement objects representing the semantic context of the generated query. Each SemanticStatement object may contain the following fields:
  • id (optional): A string representing the unique identifier of the semantic statement.
  • scope (required): A string representing the scope of the semantic statement. This is either a database, schema, table, or column name. The semantic statement will be considered whenever that object is involved in a query.
  • statement (required): A string representing the semantic statement itself (e.g., Describes the price of an item, final price is computed as 'price - discount'). This helps understand why a query was built a certain way.
  • labels (optional): An array of strings representing the labels associated with the semantic statement.
• query (optional): A string representing the generated SQL query.
• detailedSteps (optional): An array of strings providing detailed steps or actions performed by the generated SQL query. This is the textual "explain plan".
• whatChanged (optional): A string representing what changed in the query. This will be set when a generated query is refined with additional asks.
• compilationErrors (optional): An array of CompilationError objects representing any compilation errors that occurred during query generation. Each CompilationError object may contain the following fields:
  • message (required): A string representing the compilation error message.
  • line (optional): An array of numbers representing the line numbers where the compilation error occurred.
• isNew (optional): A boolean value indicating whether the generated query is new.
• timestampMs (optional): A number representing the timestamp (in milliseconds) when the query was generated.
• confidenceScore (optional): A log probability confidence score based on the tokens from generated queries.
• llmUsageStats: Token consumption during the query generation.
  • tokenTotal: Total token usage (prompt + completed). This doesn't include cached tokens. So, if you see tokenTotal = 0, the query is fetched from the cache.
• elapsedTimeMs: Total elapsed time (in milliseconds) between RPC request/response.

Running a Query

This function allows you to run a given query.

public GetQueryResultResponse run(RunQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the run query request parameters.
  • query (required): The query string to be executed.
  • sessionId (optional): The session ID for the query execution. We will use the same connection for specific sessionIds, thus it's possible to use stateful statements as well (e.g., use schema, create temporary table, etc.)
  • currentSchema: The SchemaName object to use as context when running the query. Each SchemaName object may contain the following fields:
    • schemaName (required): The name of the schema (if applicable).
    • databaseName (optional): The name of the database (if applicable).

Returns:

A GetQueryResultResponse object containing the query result details.

The GetQueryResultResponse object represents the result of a query execution and contains the following fields:

• rows (optional): An array of objects representing the rows of the query result. Each object corresponds to a row, and its properties represent the column values.
• moreRows (optional): A number indicating the number of additional rows available for the query result. If the query result exceeds the maximum returned rows, this field indicates the number of remaining rows that can be fetched.
• columnDefinitions (optional): An array of Column objects representing the column definitions of the query result. Each Column object may contain the following fields:
  • name (required): A string representing the name of the column.
  • type (required): A string representing the data type of the column.
  • comment (optional): A string representing any comment or description associated with the column.
  • sampleValues (optional): An array of ColumnSampleValues objects representing sample values for the column. Each ColumnSampleValues object may contain the following fields:
    • values (optional): An array of objects representing sample values for the column, along with their respective counts. Each object may have value (string) and count (number) properties.
• queryUuid (optional): A string representing the unique identifier of the query associated with the result.

Liking a Query

This function allows you to like or favorite a specific query. This helps finding queries in the query history, but also tells the system when queries are correct to learn from them.

public LikeQueryResponse like(LikeQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the like query request parameters.
  • queryUuid (required): The unique identifier of the query to be liked or disliked.
  • liked (required): A boolean value indicating whether to like (true) or dislike (false) the query.

Returns:

A LikeQueryResponse object confirming the success of the operation. The LikeQueryResponse object has no fields and is just a placeholder. If the query doesn't fail, the state is updated to mark the requested query as a favorite.

Submitting a Query for Execution

This function allows you to submit a query for processing. This is the same as "Running a Query" except that this function is async. It returns an id that can be used later to retrieve a query response.

public RunQueryResponse submit(RunQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the submit query request parameters.
  • query (required): The query string to be submitted.
  • sessionId (optional): The session ID for the query execution.
  • currentSchema: The SchemaName object to use as context when running the query. Each SchemaName object may contain the following fields:
    • schemaName (required): The name of the schema (if applicable).
    • databaseName (optional): The name of the database (if applicable).

Returns:

A RunQueryResponse object containing the query ID.

The RunQueryResponse object represents the response of the "run query" operation and contains the following fields:

• queryId (optional): A string representing the unique identifier of the executed query. This id is to be used in the "Get Query Results" call.
• errorDetails (optional): An object containing the error details if the query failed. The object may contain the following error codes:
  • 0 (optional): Compilation failed, but no extra information is available.
  • 1 (optional): Found a table that can’t be mapped to any of the schemas within

the database. A list of tables also present that can’t be mapped to any of the present schema.

• 2 (optional): Found unqualified tables that can’t be mapped to any single schema.
• 3 (optional): Found that more than one schema contains all the unqualified tables. Schema selection is required.
• detectedSchemas: An array of strings representing the schemas that are qualified for the query. Schema selection is required.

Transcode a Query

This function allows you to transcode a query based on the provided request parameters.

public GeneratedQuery transcode(TranscodeQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the transcode query request parameters.
  • searchContext: An array of SearchContext objects that specify the database, schema, and table names to consider during query generation. The system will automatically pick the needed objects; if this field is omitted, all the objects in the database will be considered (that's the common case).
  • sourceQuery: The source query you want to transcode.
  • sourceDialect: The dialect of the source query that you want to transcode, such as snowflake, postgresql, mongodb.
  • targetDialect: The dialect of the target query, such as snowflake, postgresql, mongodb.
  • ask: A string containing the English language statement for the query generation. Can be a question or a description of the requested result.

Returns:

A GeneratedQuery object containing the details of the generated SQL query. For a description of this object, please refer to the documentation of "Query Generation and Update".

Getting Query Results

This function allows you to get the results of a previously submitted query.

public GetQueryResultResponse getResults(GetQueryResultRequest params) throws IOException;

Parameters:

• params (required): An object containing the get query results request parameters.
  • queryId (required): The unique identifier of the query.

Returns:

A GetQueryResultResponse object containing the query result data. For a description of this object, please refer to the documentation of "Running a query".

Cancelling a Query

This function allows you to cancel a running query.

public CancelQueryResponse cancel(CancelQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the cancel query request parameters.
  • queryId (required): The unique identifier of the query to be canceled. This is the response of the "Submit Query" API.

Returns:

A CancelQueryResponse object confirming the successful cancellation.

Describing a Query

This function allows you to describe a query, providing a summary and detailed steps.

public DescribeQueryResponse describe(DescribeQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the describe query request parameters.
  • searchContext (optional): An array of SearchContext objects that specify the database, schema, and table names related to the query. This is optional; when provided, the query processing engine will only consider objects in the search context. If omitted, all objects in the database will be considered.
  • currentSchema (optional): The current schema name for the query. An optional hint to the system that the query is using a particular schema.
  • query (optional): The query string to be described.

Returns:

A DescribeQueryResponse object containing the query description details.

The DescribeQueryResponse object contains the following fields:

• summary (optional): A string representing a summary of the query's purpose or objective.
• detailedSteps (optional): An array of strings providing detailed steps or actions performed by the query.
• tables (optional): An array of TableName objects representing the tables involved in the query. Each TableName object may contain the following fields:
  • tableName (required): The name of the table.
  • schemaName (optional): The name of the schema (if applicable).
  • databaseName (optional): The name of the database (if applicable).

Autocompleting a Query

This function allows you to complete a partial query.

public AutoCompleteResponse autoComplete(AutoCompleteRequest params) throws IOException;

Parameters:

• params (required): An object containing the auto-complete query request parameters.
  • searchContext (optional): An array of SearchContext objects that specify the database, schema, and table names related to the query. This is optional; when provided, the query processing engine will only consider objects in the search context. If omitted, all objects in the database will be considered.
  • text (optional): A string containing the partial or incomplete query.
  • cursorOffset (optional): The offset in the text string where the completion is desired.
  • dialect (optional): The query dialect to use: Snowflake or PostgreSQL.
  • maxOutputTokens (optional): Maximum number of tokens to generate.

Returns:

An AutoCompleteResponse object containing the query completion details.

The AutoCompleteResponse object contains the following fields:

• text (optional): The additional text to complete the query (to be inserted at the cursorOffset given).

Showing the Difference Between Two Queries

This function allows you to diff two queries, providing a summary and detailed differences.

public DiffQueryResponse diff(DiffQueryRequest params) throws IOException;

Parameters:

• params (required): An object containing the diff query request parameters.
  • searchContext (optional): An array of SearchContext objects that specify the database, schema, and table names related to the queries. This is optional; when provided, the query processing engine will only consider objects in the search context. If omitted, all objects in the database will be considered.
  • currentSchema (optional): The current schema name for the query. An optional hint to the system that the query is using a particular schema.
  • query (optional): Query string B to be diffed.
  • previousQuery (optional): Query string A to be diffed.

Returns:

A DiffQueryResponse object containing the query diff details.

The DiffQueryResponse object contains the following fields:

• summary (optional): A string representing a summary of the query's purpose or objective.
• detailedSteps (optional): An array of strings providing detailed steps or actions performed by the query.
• tables (optional): An array of TableName objects representing the tables involved in the query. Each TableName object may contain the following fields:
  • tableName (required): The name of the table.
  • schemaName (optional): The name of the schema (if applicable).
  • databaseName (optional): The name of the database (if applicable).
• whatChanged: A description of the differences between the two queries.

Analyzing the Performance of a Query

This function allows you to get a summary of the runtime of a query as well as recommendations on how to make the query run faster.

public QueryPerformanceResponse analyzePerformance(QueryPerformanceRequest params) 
  throws IOException;

Parameters:

• params (required): An object containing the performance request parameters.
  • queryId (optional): The uuid of the query. Can be retrieved from a query submit call, Snowflake's history, or the waii query history.

Returns:

A QueryPerformanceResponse object containing the performance description details.

The QueryPerformanceResponse object contains the following fields:

• summary: A string array summarizing the runtime of the query.
• recommendations: An array of strings providing recommendations on how to improve the runtime.
• queryText: The SQL of the query.

Generating Questions from Database Schema

This function allows you to generate questions from the database schema.

public GenerateQuestionResponse generateQuestion(GenerateQuestionRequest params) throws IOException;

Parameters:

• params (required): An object containing the generate question request parameters.
  • schemaName (required): The name of the schema to generate questions from.
  • nQuestions (optional): The number of questions to generate. Default is 10.
  • complexity (optional): The complexity of the questions to generate. Default is "medium". Possible values are "easy", "medium", "hard".

Returns:

A GenerateQuestionResponse object containing the generated questions.

The GenerateQuestionResponse object contains the following fields:

• questions: A list of GeneratedQuestion objects, each containing the question text, the complexity of the question, and the tables involved in the question.