Query

View as Markdown

Query object

idstring: UUID identifying the query.
Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring: Display name of the query that appears in list views, widget headings, and on the query page.
Example: Example query

descriptionstring: General description that conveys additional information about this query such as usage notes.
Example: Example description

owner_user_namestring: Username of the user that owns the query.
Example: user@acme.com

warehouse_idstring: ID of the SQL warehouse attached to the query.
Example: a7066a8ef796be84

query_textstring: Text of the query to be run.
Example: SELECT 1

run_as_modestring: Sets the "Run as" role for the object.
Values: OWNER, VIEWER

lifecycle_statestring: Indicates whether the query is trashed.
Values: ACTIVE, TRASHED

last_modifier_user_namestring: Username of the user who last saved changes to this query.
Example: user@acme.com

parent_pathstring: Workspace path of the workspace folder containing the object.
Example: /Users/user@acme.com

tagsarray of string

create_timestring: Timestamp when this query was created.

update_timestring: Timestamp when this query was last updated.

parametersarray of object

List of query parameter definitions.

Show child attributesHide child attributes

titlestring: Text displayed in the user-facing parameter widget in the UI.

namestring: Literal parameter marker that appears between double curly braces in the query text.

text_valueobject

Text query parameter value.

Show child attributesHide child attributes

valuestring

numeric_valueobject

Numeric query parameter value.

Show child attributesHide child attributes

valuedouble

enum_valueobject

Dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

enum_optionsstring: List of valid query parameter values, newline delimited.

multi_values_optionsobject

If specified, allows multiple values to be selected for this parameter.

Show child attributesHide child attributes

prefixstring: Character that prefixes each selected parameter value.

separatorstring: Character that separates each selected parameter value. Defaults to a comma.

suffixstring: Character that suffixes each selected parameter value.

date_valueobject

Date query parameter value. Can only specify one of dynamic_date_value or date_value.

Show child attributesHide child attributes

dynamic_date_valuestring: Dynamic date-time value based on current date-time.
Values: NOW, YESTERDAY

date_valuestring: Manually specified date-time value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

date_range_valueobject

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes

dynamic_date_range_valuestring: Dynamic date-time range value based on current date-time.
Values: TODAY, YESTERDAY, THIS_WEEK, THIS_MONTH, THIS_YEAR, LAST_WEEK, LAST_MONTH, LAST_YEAR, LAST_HOUR, LAST_8_HOURS, LAST_24_HOURS, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_60_DAYS, LAST_90_DAYS, LAST_12_MONTHS

date_range_valueobject

Manually specified date-time range value.

Show child attributesHide child attributes

startstring

endstring

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

start_day_of_weekint32

query_backed_valueobject

Query-based dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

query_idstring: UUID of the query that provides the parameter values.

multi_values_optionsobject

If specified, allows multiple values to be selected for this parameter.

Show child attributesHide child attributes

prefixstring: Character that prefixes each selected parameter value.

separatorstring: Character that separates each selected parameter value. Defaults to a comma.

suffixstring: Character that suffixes each selected parameter value.

apply_auto_limitboolean: Whether to apply a 1000 row limit to the query result.

catalogstring: Name of the catalog where this query will be executed.

schemastring: Name of the schema where this query will be executed.

View as Markdown

The Query object

{
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "display_name": "Example query",
  "description": "Example description",
  "owner_user_name": "user@acme.com",
  "warehouse_id": "a7066a8ef796be84",
  "query_text": "SELECT 1",
  "run_as_mode": "string",
  "lifecycle_state": "string",
  "last_modifier_user_name": "user@acme.com",
  "parent_path": "/Users/user@acme.com",
  "tags": [
    "string"
  ],
  "create_time": "string",
  "update_time": "string",
  "parameters": [
    {
      "title": "string",
      "name": "string",
      "text_value": {},
      "numeric_value": {},
      "enum_value": {},
      "date_value": {},
      "date_range_value": {},
      "query_backed_value": {}
    }
  ],
  "apply_auto_limit": true,
  "catalog": "string",
  "schema": "string"
}

Get GA

GET /api/2.0/sql/queries/{id}

Gets a query.

API scopes: sql

Parameters

idstringpath

Response

Returns the Query object.

View as Markdown

Response

{
  "create_time": "2019-08-24T14:15:22Z",
  "description": "Example description",
  "display_name": "Example query",
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "last_modifier_user_name": "user@acme.com",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parameters": [
    {
      "name": "foo",
      "text_value": {
        "value": "bar"
      },
      "title": "foo"
    }
  ],
  "parent_path": "/Workspace/Users/user@acme.com",
  "query_text": "SELECT 1",
  "run_as_mode": "OWNER",
  "tags": [
    "Tag 1"
  ],
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "a7066a8ef796be84"
}

List GA

GET /api/2.0/sql/queries

Gets a list of queries accessible to the user, ordered by creation time. Warning: Calling this API concurrently 10 or more times could result in throttling, service degradation, or a temporary ban.

API scopes: sql

Parameters

page_tokenstringquery

page_sizeint32query: Default: 20
Constraints: <= 100

Response

resultsarray of object

Show child attributesHide child attributes

idstring: UUID identifying the query.
Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring: Display name of the query that appears in list views, widget headings, and on the query page.
Example: Example query

descriptionstring: General description that conveys additional information about this query such as usage notes.
Example: Example description

owner_user_namestring: Username of the user that owns the query.
Example: user@acme.com

warehouse_idstring: ID of the SQL warehouse attached to the query.
Example: a7066a8ef796be84

query_textstring: Text of the query to be run.
Example: SELECT 1

run_as_modestring: Sets the "Run as" role for the object.
Values: OWNER, VIEWER

lifecycle_statestring: Indicates whether the query is trashed.
Values: ACTIVE, TRASHED

last_modifier_user_namestring: Username of the user who last saved changes to this query.
Example: user@acme.com

parent_pathstring: Workspace path of the workspace folder containing the object.
Example: /Users/user@acme.com

tagsarray of string

create_timestring: Timestamp when this query was created.

update_timestring: Timestamp when this query was last updated.

parametersarray of object

List of query parameter definitions.

Show child attributesHide child attributes

titlestring: Text displayed in the user-facing parameter widget in the UI.

namestring: Literal parameter marker that appears between double curly braces in the query text.

text_valueobjectRequired

Text query parameter value.

Show child attributesHide child attributes

valuestring

numeric_valueobjectRequired

Numeric query parameter value.

Show child attributesHide child attributes

valuedouble

enum_valueobjectRequired

Dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

enum_optionsstring: List of valid query parameter values, newline delimited.

multi_values_optionsobject: If specified, allows multiple values to be selected for this parameter.

date_valueobjectRequired

Date query parameter value. Can only specify one of dynamic_date_value or date_value.

Show child attributesHide child attributes

dynamic_date_valuestringRequired: Dynamic date-time value based on current date-time.
Values: NOW, YESTERDAY

date_valuestringRequired: Manually specified date-time value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

date_range_valueobjectRequired

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes

dynamic_date_range_valuestringRequired: Dynamic date-time range value based on current date-time.
Values: TODAY, YESTERDAY, THIS_WEEK, THIS_MONTH, THIS_YEAR, LAST_WEEK, LAST_MONTH, LAST_YEAR, LAST_HOUR, LAST_8_HOURS, LAST_24_HOURS, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_60_DAYS, LAST_90_DAYS, LAST_12_MONTHS

date_range_valueobjectRequired: Manually specified date-time range value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

start_day_of_weekint32

query_backed_valueobjectRequired

Query-based dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

query_idstring: UUID of the query that provides the parameter values.

multi_values_optionsobject: If specified, allows multiple values to be selected for this parameter.

apply_auto_limitboolean: Whether to apply a 1000 row limit to the query result.

catalogstring: Name of the catalog where this query will be executed.

schemastring: Name of the schema where this query will be executed.

next_page_tokenstring

View as Markdown

Response

{
  "next_page_token": "eDg",
  "results": [
    {
      "create_time": "2019-08-24T14:15:22Z",
      "description": "Example description",
      "display_name": "Example query 1",
      "id": "ae25e731-92f2-4838-9fb2-1ca364320a3d",
      "last_modifier_user_name": "user@acme.com",
      "lifecycle_state": "ACTIVE",
      "owner_user_name": "user@acme.com",
      "parameters": [
        {
          "name": "foo",
          "text_value": {
            "value": "bar"
          },
          "title": "foo"
        }
      ],
      "query_text": "SELECT 1",
      "run_as_mode": "OWNER",
      "tags": [
        "Tag 1"
      ],
      "update_time": "2019-08-24T14:15:22Z",
      "warehouse_id": "a7066a8ef796be84"
    },
    {
      "create_time": "2019-08-24T14:15:22Z",
      "description": "Example description",
      "display_name": "Example query 2",
      "id": "be25e731-92f2-4838-9fb2-1ca364320a3d",
      "last_modifier_user_name": "user@acme.com",
      "lifecycle_state": "ACTIVE",
      "owner_user_name": "user@acme.com",
      "parameters": [
        {
          "name": "foo",
          "text_value": {
            "value": "bar"
          },
          "title": "foo"
        }
      ],
      "query_text": "SELECT 1",
      "run_as_mode": "OWNER",
      "tags": [
        "Tag 1"
      ],
      "update_time": "2019-08-24T14:15:22Z",
      "warehouse_id": "a7066a8ef796be84"
    }
  ]
}

Create GA

POST /api/2.0/sql/queries

Creates a query.

API scopes: sql

Request body

queryobject

Show child attributesHide child attributes

idstring: UUID identifying the query.
Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring: Display name of the query that appears in list views, widget headings, and on the query page.
Example: Example query

descriptionstring: General description that conveys additional information about this query such as usage notes.
Example: Example description

owner_user_namestring: Username of the user that owns the query.
Example: user@acme.com

warehouse_idstring: ID of the SQL warehouse attached to the query.
Example: a7066a8ef796be84

query_textstring: Text of the query to be run.
Example: SELECT 1

run_as_modestring: Sets the "Run as" role for the object.
Values: OWNER, VIEWER

lifecycle_statestring: Indicates whether the query is trashed.
Values: ACTIVE, TRASHED

last_modifier_user_namestring: Username of the user who last saved changes to this query.
Example: user@acme.com

parent_pathstring: Workspace path of the workspace folder containing the object.
Example: /Users/user@acme.com

tagsarray of string

create_timestring: Timestamp when this query was created.

update_timestring: Timestamp when this query was last updated.

parametersarray of object

List of query parameter definitions.

Show child attributesHide child attributes

titlestring: Text displayed in the user-facing parameter widget in the UI.

namestring: Literal parameter marker that appears between double curly braces in the query text.

text_valueobjectRequired

Text query parameter value.

Show child attributesHide child attributes

valuestring

numeric_valueobjectRequired

Numeric query parameter value.

Show child attributesHide child attributes

valuedouble

enum_valueobjectRequired

Dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

enum_optionsstring: List of valid query parameter values, newline delimited.

multi_values_optionsobject: If specified, allows multiple values to be selected for this parameter.

date_valueobjectRequired

Date query parameter value. Can only specify one of dynamic_date_value or date_value.

Show child attributesHide child attributes

dynamic_date_valuestringRequired: Dynamic date-time value based on current date-time.
Values: NOW, YESTERDAY

date_valuestringRequired: Manually specified date-time value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

date_range_valueobjectRequired

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes

dynamic_date_range_valuestringRequired: Dynamic date-time range value based on current date-time.
Values: TODAY, YESTERDAY, THIS_WEEK, THIS_MONTH, THIS_YEAR, LAST_WEEK, LAST_MONTH, LAST_YEAR, LAST_HOUR, LAST_8_HOURS, LAST_24_HOURS, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_60_DAYS, LAST_90_DAYS, LAST_12_MONTHS

date_range_valueobjectRequired: Manually specified date-time range value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

start_day_of_weekint32

query_backed_valueobjectRequired

Query-based dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

query_idstring: UUID of the query that provides the parameter values.

multi_values_optionsobject: If specified, allows multiple values to be selected for this parameter.

apply_auto_limitboolean: Whether to apply a 1000 row limit to the query result.

catalogstring: Name of the catalog where this query will be executed.

schemastring: Name of the schema where this query will be executed.

auto_resolve_display_nameboolean: If true, automatically resolve query display name conflicts. Otherwise, fail the request if the query's display name conflicts with an existing query's display name.
Default: true

Response

Returns the Query object.

View as Markdown

Request

{
  "query": {
    "description": "Example description",
    "display_name": "Example query",
    "parameters": [
      {
        "name": "foo",
        "text_value": {
          "value": "bar"
        },
        "title": "foo"
      }
    ],
    "parent_path": "/Workspace/Users/user@acme.com",
    "query_text": "SELECT 1",
    "run_as_mode": "OWNER",
    "tags": [
      "Tag 1"
    ],
    "warehouse_id": "a7066a8ef796be84"
  }
}

Response

{
  "create_time": "2019-08-24T14:15:22Z",
  "description": "Example description",
  "display_name": "Example query",
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "last_modifier_user_name": "user@acme.com",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parameters": [
    {
      "name": "foo",
      "text_value": {
        "value": "bar"
      },
      "title": "foo"
    }
  ],
  "parent_path": "/Workspace/Users/user@acme.com",
  "query_text": "SELECT 1",
  "run_as_mode": "OWNER",
  "tags": [
    "Tag 1"
  ],
  "warehouse_id": "a7066a8ef796be84"
}

Update GA

PATCH /api/2.0/sql/queries/{id}

Updates a query.

API scopes: sql

Parameters

idstringpath

Request body

queryobject

Show child attributesHide child attributes

idstring: UUID identifying the query.
Example: fe25e731-92f2-4838-9fb2-1ca364320a3d

display_namestring: Display name of the query that appears in list views, widget headings, and on the query page.
Example: Example query

descriptionstring: General description that conveys additional information about this query such as usage notes.
Example: Example description

owner_user_namestring: Username of the user that owns the query.
Example: user@acme.com

warehouse_idstring: ID of the SQL warehouse attached to the query.
Example: a7066a8ef796be84

query_textstring: Text of the query to be run.
Example: SELECT 1

run_as_modestring: Sets the "Run as" role for the object.
Values: OWNER, VIEWER

lifecycle_statestring: Indicates whether the query is trashed.
Values: ACTIVE, TRASHED

last_modifier_user_namestring: Username of the user who last saved changes to this query.
Example: user@acme.com

parent_pathstring: Workspace path of the workspace folder containing the object.
Example: /Users/user@acme.com

tagsarray of string

create_timestring: Timestamp when this query was created.

update_timestring: Timestamp when this query was last updated.

parametersarray of object

List of query parameter definitions.

Show child attributesHide child attributes

titlestring: Text displayed in the user-facing parameter widget in the UI.

namestring: Literal parameter marker that appears between double curly braces in the query text.

text_valueobjectRequired

Text query parameter value.

Show child attributesHide child attributes

valuestring

numeric_valueobjectRequired

Numeric query parameter value.

Show child attributesHide child attributes

valuedouble

enum_valueobjectRequired

Dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

enum_optionsstring: List of valid query parameter values, newline delimited.

multi_values_optionsobject: If specified, allows multiple values to be selected for this parameter.

date_valueobjectRequired

Date query parameter value. Can only specify one of dynamic_date_value or date_value.

Show child attributesHide child attributes

dynamic_date_valuestringRequired: Dynamic date-time value based on current date-time.
Values: NOW, YESTERDAY

date_valuestringRequired: Manually specified date-time value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

date_range_valueobjectRequired

Date-range query parameter value. Can only specify one of dynamic_date_range_value or date_range_value.

Show child attributesHide child attributes

dynamic_date_range_valuestringRequired: Dynamic date-time range value based on current date-time.
Values: TODAY, YESTERDAY, THIS_WEEK, THIS_MONTH, THIS_YEAR, LAST_WEEK, LAST_MONTH, LAST_YEAR, LAST_HOUR, LAST_8_HOURS, LAST_24_HOURS, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_60_DAYS, LAST_90_DAYS, LAST_12_MONTHS

date_range_valueobjectRequired: Manually specified date-time range value.

precisionstring: Date-time precision to format the value into when the query is run. Defaults to DAY_PRECISION (YYYY-MM-DD).
Values: DAY_PRECISION, MINUTE_PRECISION, SECOND_PRECISION

start_day_of_weekint32

query_backed_valueobjectRequired

Query-based dropdown query parameter value.

Show child attributesHide child attributes

valuesarray of string: List of selected query parameter values.

query_idstring: UUID of the query that provides the parameter values.

multi_values_optionsobject: If specified, allows multiple values to be selected for this parameter.

apply_auto_limitboolean: Whether to apply a 1000 row limit to the query result.

catalogstring: Name of the catalog where this query will be executed.

schemastring: Name of the schema where this query will be executed.

update_maskstring

auto_resolve_display_nameboolean: If true, automatically resolve alert display name conflicts. Otherwise, fail the request if the alert's display name conflicts with an existing alert's display name.
Default: true

Response

Returns the Query object.

View as Markdown

Request

{
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "query": {
    "description": "Example description updated",
    "display_name": "Example query updated",
    "query_text": "SELECT 2"
  },
  "update_mask": "display_name,description,query_text"
}

Response

{
  "create_time": "2019-08-24T14:15:22Z",
  "description": "Example description updated",
  "display_name": "Example query updated",
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "last_modifier_user_name": "user@acme.com",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parameters": [
    {
      "name": "foo",
      "text_value": {
        "value": "bar"
      },
      "title": "foo"
    }
  ],
  "parent_path": "/Workspace/Users/user@acme.com",
  "query_text": "SELECT 2",
  "run_as_mode": "OWNER",
  "tags": [
    "Tag 1"
  ],
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "a7066a8ef796be84"
}

Delete GA

DELETE /api/2.0/sql/queries/{id}

Moves a query to the trash. Trashed queries immediately disappear from searches and list views, and cannot be used for alerts. You can restore a trashed query through the UI. A trashed query is permanently deleted after 30 days.

API scopes: sql

Parameters

idstringpath

Query object​

Get GA​

Parameters​

Response​

List GA​

Parameters​

Response​

Create GA​

Request body​

Response​

Update GA​

Parameters​

Request body​

Response​

Delete GA​

Parameters​

Query object

Get GA

Parameters

Response

List GA

Parameters

Response

Create GA

Request body

Response

Update GA

Parameters

Request body

Response

Delete GA

Parameters