User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Query : Run and Manage Queries

Run Query Async beta

POST/api/3.1/query_tasks
create_query_task(body, limit, apply_formatting, apply_vis, cache, image_width, image_height, generate_drill_links, force_production, cache_only, path_prefix, rebuild_pdts, server_table_calcs, fields)

Implementation Notes

Run a saved query asynchronously.

Runs a previously created query asynchronously. Returns a Query Task ID which can be used to fetch the results from the Query Tasks results endpoint.

Response Class

QueryTask {
id (string, read-only): Unique Id,
query_id (long): Id of query,
query (Query, read-only): Query,
generate_links (boolean): whether or not to generate links in the query response.,
force_production (boolean): Use production models to run query (even is user is in dev mode).,
path_prefix (string): Prefix to use for drill links.,
cache (boolean): Whether or not to use the cache,
server_table_calcs (boolean): Whether or not to run table calculations on the server,
cache_only (boolean): Retrieve any results from cache even if the results have expired.,
cache_key (string, read-only): cache key used to cache query.,
status (string): Status of query task.,
source (string): Source of query task.,
runtime (float, read-only): Runtime of prior queries.,
rebuild_pdts (boolean): Rebuild PDTS used in query.,
result_source (string, read-only): Source of the results of the query.,
look_id (long): Id of look associated with query.,
dashboard_id (string): Id of dashboard associated with query.,
result_format (string, read-only): The data format of the query results.,
can (object, read-only): Operations the current user is able to perform on this object
}
Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
body true Query parameters body
CreateQueryTask {
query_id (long, required): Id of query to run,
result_format (string, required): Desired result format,
source (string): Source of query task,
deferred (boolean): Create the task but defer execution,
look_id (long): Id of look associated with query.,
dashboard_id (string): Id of dashboard associated with query.,
can (object, read-only): Operations the current user is able to perform on this object
}
limit false Row limit (may override the limit in the saved query). integer int64
apply_formatting false Apply model-specified formatting to each result. boolean boolean
apply_vis false Apply visualization options to results. boolean boolean
cache false Get results from cache if available. boolean boolean
image_width false Render width for image formats. integer int64
image_height false Render height for image formats. integer int64
generate_drill_links false Generate drill links (only applicable to ‘json_detail’ format. boolean boolean
force_production false Force use of production models even if the user is in development mode. boolean boolean
cache_only false Retrieve any results from cache even if the results have expired. boolean boolean
path_prefix false Prefix to use for drill links (url encoded). string string
rebuild_pdts false Rebuild PDTS used in query. boolean boolean
server_table_calcs false Perform table calculations on query results boolean boolean
fields false Requested fields string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
409 Resource Already Exists
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}

Get Multiple Async Query Results beta

GET/api/3.1/query_tasks/multi_results
query_task_multi_results(query_task_ids)

Implementation Notes

Fetch the results of multiple async Query Tasks in one response.

For Query Tasks that are not completed, the response will include the execution status of the Query Task but will not include query results. Query Tasks whose results have expired will have a status of ‘expired’. If the user making the API request does not have sufficient privileges to view a Query Task result, the result will have a status of ‘missing’

Response Class

  object

Parameters

Parameter Required? Description Parameter Type Data Type
query_task_ids true List of Query Task IDs array array

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Get Async Query Info beta

GET/api/3.1/query_tasks/{query_task_id}
query_task(query_task_id, fields)

Implementation Notes

Returns information about a Query Task.

Query Tasks are generated by running queries asynchronously. They are represented by a GUID returned from one of the async query endpoints.

Response Class

QueryTask {
id (string, read-only): Unique Id,
query_id (long): Id of query,
query (Query, read-only): Query,
generate_links (boolean): whether or not to generate links in the query response.,
force_production (boolean): Use production models to run query (even is user is in dev mode).,
path_prefix (string): Prefix to use for drill links.,
cache (boolean): Whether or not to use the cache,
server_table_calcs (boolean): Whether or not to run table calculations on the server,
cache_only (boolean): Retrieve any results from cache even if the results have expired.,
cache_key (string, read-only): cache key used to cache query.,
status (string): Status of query task.,
source (string): Source of query task.,
runtime (float, read-only): Runtime of prior queries.,
rebuild_pdts (boolean): Rebuild PDTS used in query.,
result_source (string, read-only): Source of the results of the query.,
look_id (long): Id of look associated with query.,
dashboard_id (string): Id of dashboard associated with query.,
result_format (string, read-only): The data format of the query results.,
can (object, read-only): Operations the current user is able to perform on this object
}
Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
query_task_id true ID of the Query Task string string
fields false Requested fields. string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Get Async Query Results beta

GET/api/3.1/query_tasks/{query_task_id}/results
query_task_results(query_task_id)

Implementation Notes

Returns the results of an async Query Task if the query has completed.

Response Class

  object

Parameters

Parameter Required? Description Parameter Type Data Type
query_task_id true ID of the Query Task string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 The Query Task Id was not found or the results have expired.
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
204 The query is not finished string

Get Query

GET/api/3.1/queries/{query_id}
query(query_id, fields)

Implementation Notes

Get a previously created query by id.

A Looker query object includes the various parameters that define a database query that has been run or could be run in the future. These parameters include: model, view, fields, filters, pivots, etc. Query results are not part of the query object.

Query objects are unique and immutable. Query objects are created automatically in Looker as users explore data. Looker does not delete them; they become part of the query history. When asked to create a query for any given set of parameters, Looker will first try to find an existing query object with matching parameters and will only create a new object when an appropriate object can not be found.

This ‘get’ method is used to get the details about a query for a given id. See the other methods here to ‘create’ and ‘run’ queries.

Note that some fields like ‘filter_config’ and ‘vis_config’ etc are specific to how the Looker UI builds queries and visualizations and are not generally useful for API use. They are not required when creating new queries and can usually just be ignored.

Response Class

Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
query_id true Id of query integer int64
fields false Requested fields. string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Get Query for Slug

GET/api/3.1/queries/slug/{slug}
query_for_slug(slug, fields)

Implementation Notes

Get the query for a given query slug.

This returns the query for the ‘slug’ in a query share URL.

The ‘slug’ is a randomly chosen short string that is used as an alternative to the query’s id value for use in URLs etc. This method exists as a convenience to help you use the API to ‘find’ queries that have been created using the Looker UI.

You can use the Looker explore page to build a query and then choose the ‘Share’ option to show the share url for the query. Share urls generally look something like ‘https://looker.yourcompany/x/vwGSbfc’. The trailing ‘vwGSbfc’ is the share slug. You can pass that string to this api method to get details about the query. Those details include the ‘id’ that you can use to run the query. Or, you can copy the query body (perhaps with your own modification) and use that as the basis to make/run new queries.

This will also work with slugs from Looker explore urls like ‘https://looker.yourcompany/explore/ecommerce/orders?qid=aogBgL6o3cKK1jN3RoZl5s’. In this case ‘aogBgL6o3cKK1jN3RoZl5s’ is the slug.

Response Class

Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
slug true Slug of query string string
fields false Requested fields. string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Create Query

POST/api/3.1/queries
create_query(body, fields)

Implementation Notes

Create a query.

This allows you to create a new query that you can later run. Looker queries are immutable once created and are not deleted. If you create a query that is exactly like an existing query then the existing query will be returned and no new query will be created. Whether a new query is created or not, you can use the ‘id’ in the returned query with the ‘run’ method.

The query parameters are passed as json in the body of the request.

Response Class

Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
body false Query body
Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}
fields false Requested fields. string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
409 Resource Already Exists
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}

Run Query

GET/api/3.1/queries/{query_id}/run/{result_format}
run_query(query_id, result_format, limit, apply_formatting, apply_vis, cache, image_width, image_height, generate_drill_links, force_production, cache_only, path_prefix, rebuild_pdts, server_table_calcs)

Implementation Notes

Run a saved query.

This runs a previously saved query. You can use this on a query that was generated in the Looker UI or one that you have explicitly created using the API. You can also use a query ‘id’ from a saved ‘Look’.

The ‘result_format’ parameter specifies the desired structure and format of the response.

Supported formats:

result_format Description
json Plain json
json_detail Row data plus metadata describing the fields, pivots, table calcs, and other aspects of the query
csv Comma separated values with a header
txt Tab separated values with a header
html Simple html
md Simple markdown
xlsx MS Excel spreadsheet
sql Returns the generated SQL rather than running the query
png A PNG image of the visualization of the query
jpg A JPG image of the visualization of the query

Response Class

  string

Parameters

Parameter Required? Description Parameter Type Data Type
query_id true Id of query integer int64
result_format true Format of result string string
limit false Row limit (may override the limit in the saved query). integer int64
apply_formatting false Apply model-specified formatting to each result. boolean boolean
apply_vis false Apply visualization options to results. boolean boolean
cache false Get results from cache if available. boolean boolean
image_width false Render width for image formats. integer int64
image_height false Render height for image formats. integer int64
generate_drill_links false Generate drill links (only applicable to ‘json_detail’ format. boolean boolean
force_production false Force use of production models even if the user is in development mode. boolean boolean
cache_only false Retrieve any results from cache even if the results have expired. boolean boolean
path_prefix false Prefix to use for drill links (url encoded). string string
rebuild_pdts false Rebuild PDTS used in query. boolean boolean
server_table_calcs false Perform table calculations on query results boolean boolean

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}

Run Inline Query

POST/api/3.1/queries/run/{result_format}
run_inline_query(result_format, body, limit, apply_formatting, apply_vis, cache, image_width, image_height, generate_drill_links, force_production, cache_only, path_prefix, rebuild_pdts, server_table_calcs)

Implementation Notes

Run the query that is specified inline in the posted body.

This allows running a query as defined in json in the posted body. This combines the two actions of posting & running a query into one step.

Here is an example body in json:

{
  "model":"thelook",
  "view":"inventory_items",
  "fields":["category.name","inventory_items.days_in_inventory_tier","products.count"],
  "filters":{"category.name":"socks"},
  "sorts":["products.count desc 0"],
  "limit":"500",
  "query_timezone":"America/Los_Angeles"
}

When using the Ruby SDK this would be passed as a Ruby hash like:

{
 :model=>"thelook",
 :view=>"inventory_items",
 :fields=>
  ["category.name",
   "inventory_items.days_in_inventory_tier",
   "products.count"],
 :filters=>{:"category.name"=>"socks"},
 :sorts=>["products.count desc 0"],
 :limit=>"500",
 :query_timezone=>"America/Los_Angeles",
}

This will return the result of running the query in the format specified by the ‘result_format’ parameter.

Supported formats:

result_format Description
json Plain json
json_detail Row data plus metadata describing the fields, pivots, table calcs, and other aspects of the query
csv Comma separated values with a header
txt Tab separated values with a header
html Simple html
md Simple markdown
xlsx MS Excel spreadsheet
sql Returns the generated SQL rather than running the query
png A PNG image of the visualization of the query
jpg A JPG image of the visualization of the query

Response Class

  string

Parameters

Parameter Required? Description Parameter Type Data Type
result_format true Format of result string string
body true inline query body
Query {
id (long, read-only): Unique Id,
model (string, required): Model,
view (string, required): Explore Name,
fields (Array[string]): Fields,
pivots (Array[string]): Pivots,
fill_fields (Array[string]): Fill Fields,
filters (object): Filters,
filter_expression (string): Filter Expression,
sorts (Array[string]): Sorting for the query results. Use the format ["view.field", ...] to sort on fields in ascending order. Use the format ["view.field desc", ...] to sort on fields in descending order. Use ["__UNSORTED__"] (2 underscores before and after) to disable sorting entirely. Empty sorts [] will trigger a default sort.,
limit (string): Limit,
column_limit (string): Column Limit,
total (boolean): Total,
row_total (string): Raw Total,
subtotals (Array[string]): Fields on which to run subtotals,
runtime (double): Runtime,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
filter_config (object): The filter_config represents the state of the filter UI on the explore page for a given query. When running a query via the Looker UI, this parameter takes precedence over "filters". When creating a query or modifying an existing query, "filter_config" should be set to null. Setting it to any other value could cause unexpected filtering behavior. The format should be considered opaque.,
visible_ui_sections (string): Visible UI Sections,
slug (string, read-only): Slug,
dynamic_fields (string): Dynamic Fields,
client_id (string): Client Id: used to generate shortened explore URLs. If set by client, must be a unique 22 character alphanumeric string. Otherwise one will be generated.,
share_url (string, read-only): Share Url,
expanded_share_url (string, read-only): Expanded Share Url,
url (string, read-only): Expanded Url,
query_timezone (string): Query Timezone,
has_table_calculations (boolean, read-only): Has Table Calculations,
can (object, read-only): Operations the current user is able to perform on this object
}
limit false Row limit (may override the limit in the saved query). integer int64
apply_formatting false Apply model-specified formatting to each result. boolean boolean
apply_vis false Apply visualization options to results. boolean boolean
cache false Get results from cache if available. boolean boolean
image_width false Render width for image formats. integer int64
image_height false Render height for image formats. integer int64
generate_drill_links false Generate drill links (only applicable to ‘json_detail’ format. boolean boolean
force_production false Force use of production models even if the user is in development mode. boolean boolean
cache_only false Retrieve any results from cache even if the results have expired. boolean boolean
path_prefix false Prefix to use for drill links (url encoded). string string
rebuild_pdts false Rebuild PDTS used in query. boolean boolean
server_table_calcs false Perform table calculations on query results boolean boolean

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Run Url Encoded Query

GET/api/3.1/queries/models/{model_name}/views/{view_name}/run/{result_format}
run_url_encoded_query(model_name, view_name, result_format)

Implementation Notes

Run an URL encoded query.

This requires the caller to encode the specifiers for the query into the URL query part using Looker-specific syntax as explained below.

Generally, you would want to use one of the methods that takes the parameters as json in the POST body for creating and/or running queries. This method exists for cases where one really needs to encode the parameters into the URL of a single ‘GET’ request. This matches the way that the Looker UI formats ‘explore’ URLs etc.

The parameters here are very similar to the json body formatting except that the filter syntax is tricky. Unfortunately, this format makes this method not currently callible via the ‘Try it out!’ button in this documentation page. But, this is callable when creating URLs manually or when using the Looker SDK.

Here is an example inline query URL:

https://looker.mycompany.com:19999/api/3.0/queries/models/thelook/views/inventory_items/run/json?fields=category.name,inventory_items.days_in_inventory_tier,products.count&f[category.name]=socks&sorts=products.count+desc+0&limit=500&query_timezone=America/Los_Angeles

When invoking this endpoint with the Ruby SDK, pass the query parameter parts as a hash. The hash to match the above would look like:

query_params =
{
  :fields => "category.name,inventory_items.days_in_inventory_tier,products.count",
  :"f[category.name]" => "socks",
  :sorts => "products.count desc 0",
  :limit => "500",
  :query_timezone => "America/Los_Angeles"
}
response = ruby_sdk.run_url_encoded_query('thelook','inventory_items','json', query_params)

Again, it is generally easier to use the variant of this method that passes the full query in the POST body. This method is available for cases where other alternatives won’t fit the need.

Supported formats:

result_format Description
json Plain json
json_detail Row data plus metadata describing the fields, pivots, table calcs, and other aspects of the query
csv Comma separated values with a header
txt Tab separated values with a header
html Simple html
md Simple markdown
xlsx MS Excel spreadsheet
sql Returns the generated SQL rather than running the query
png A PNG image of the visualization of the query
jpg A JPG image of the visualization of the query

Response Class

  string

Parameters

Parameter Required? Description Parameter Type Data Type
model_name true Model name string string
view_name true View name string string
result_format true Format of result string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}

Get Merge Query beta

GET/api/3.1/merge_queries/{merge_query_id}
merge_query(merge_query_id, fields)

Implementation Notes

Get Merge Query.

Returns a merge query object given its id.

Response Class

MergeQuery {
column_limit (string): Column Limit,
dynamic_fields (string): Dynamic Fields,
id (string, read-only): Unique Id,
pivots (Array[string]): Pivots,
result_maker_id (long, read-only): Unique to get results,
sorts (Array[string]): Sorts,
source_queries (Array[MergeQuerySourceQuery]): Source Queries defining the results to be merged.,
total (boolean): Total,
vis_config (object): Visualization Config,
can (object, read-only): Operations the current user is able to perform on this object
}
MergeQuerySourceQuery {
merge_fields (Array[MergeFields]): An array defining which fields of the source query are mapped onto fields of the merge query,
name (string): Display name,
query_id (long): Id of the query to merge
}
MergeFields {
field_name (string): Field name to map onto in the merged results,
source_field_name (string): Field name from the source query
}

Parameters

Parameter Required? Description Parameter Type Data Type
merge_query_id true Merge Query Id string string
fields false Requested fields string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Create Merge Query beta

POST/api/3.1/merge_queries
create_merge_query(body, fields)

Implementation Notes

Create Merge Query.

Creates a new merge query object.

A merge query takes the results of one or more queries and combines (merges) the results according to field mapping definitions. The result is similar to a SQL left outer join.

A merge query can merge results of queries from different SQL databases.

The order that queries are defined in the source_queries array property is significant. The first query in the array defines the primary key into which the results of subsequent queries will be merged.

Like model/view query objects, merge queries are immutable and have structural identity - if you make a request to create a new merge query that is identical to an existing merge query, the existing merge query will be returned instead of creating a duplicate. Conversely, any change to the contents of a merge query will produce a new object with a new id.

Response Class

MergeQuery {
column_limit (string): Column Limit,
dynamic_fields (string): Dynamic Fields,
id (string, read-only): Unique Id,
pivots (Array[string]): Pivots,
result_maker_id (long, read-only): Unique to get results,
sorts (Array[string]): Sorts,
source_queries (Array[MergeQuerySourceQuery]): Source Queries defining the results to be merged.,
total (boolean): Total,
vis_config (object): Visualization Config,
can (object, read-only): Operations the current user is able to perform on this object
}
MergeQuerySourceQuery {
merge_fields (Array[MergeFields]): An array defining which fields of the source query are mapped onto fields of the merge query,
name (string): Display name,
query_id (long): Id of the query to merge
}
MergeFields {
field_name (string): Field name to map onto in the merged results,
source_field_name (string): Field name from the source query
}

Parameters

Parameter Required? Description Parameter Type Data Type
body false Merge Query body
MergeQuery {
column_limit (string): Column Limit,
dynamic_fields (string): Dynamic Fields,
id (string, read-only): Unique Id,
pivots (Array[string]): Pivots,
result_maker_id (long, read-only): Unique to get results,
sorts (Array[string]): Sorts,
source_queries (Array[MergeQuerySourceQuery]): Source Queries defining the results to be merged.,
total (boolean): Total,
vis_config (object): Visualization Config,
can (object, read-only): Operations the current user is able to perform on this object
}
MergeQuerySourceQuery {
merge_fields (Array[MergeFields]): An array defining which fields of the source query are mapped onto fields of the merge query,
name (string): Display name,
query_id (long): Id of the query to merge
}
MergeFields {
field_name (string): Field name to map onto in the merged results,
source_field_name (string): Field name from the source query
}
fields false Requested fields string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
409 Resource Already Exists
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}

Get All Running Queries

GET/api/3.1/running_queries
all_running_queries()

Implementation Notes

Get information about all running queries.

Response Class

  array

Parameters

  None

Response Messages

HTTP Status Code Reason Response Model
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Kill Running Query

DELETE/api/3.1/running_queries/{query_task_id}
kill_query(query_task_id)

Implementation Notes

Kill a query with a specific query_task_id.

Response Class

  None

Parameters

Parameter Required? Description Parameter Type Data Type
query_task_id true Query task id. string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}
204 Query successfully killed. string

Get SQL Runner Query beta

GET/api/3.1/sql_queries/{slug}
sql_query(slug)

Implementation Notes

Get a SQL Runner query.

Response Class

SqlQuery {
slug (string, read-only): The identifier of the SQL query,
last_runtime (float, read-only): Number of seconds this query took to run the most recent time it was run,
run_count (long, read-only): Number of times this query has been run,
browser_limit (long, read-only): Maximum number of rows this query will display on the SQL Runner page,
sql (string, read-only): SQL query text,
last_run_at (string, read-only): The most recent time this query was run,
connection (DBConnectionBase, read-only): Connection this query uses,
model_name (string, read-only): Model name this query uses,
creator (UserPublic, read-only): User who created this SQL query,
explore_url (string, read-only): Explore page URL for this SQL query,
plaintext (boolean, read-only): Should this query be rendered as plain text,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
can (object, read-only): Operations the current user is able to perform on this object
}
DBConnectionBase {
name (string, read-only): Name of the connection. Also used as the unique identifier,
dialect (Dialect, read-only): (Read-only) SQL Dialect details,
snippets (Array[Snippet], read-only): SQL Runner snippets for this connection,
can (object, read-only): Operations the current user is able to perform on this object
}
Dialect {
name (string, read-only): The name of the dialect,
label (string, read-only): The human-readable label of the connection,
supports_cost_estimate (boolean, read-only): Whether the dialect supports query cost estimates,
supports_upload_tables (boolean, read-only): Whether the dialect supports uploading tables,
persistent_table_indexes (string, read-only): PDT index columns,
persistent_table_sortkeys (string, read-only): PDT sortkey columns,
persistent_table_distkey (string, read-only): PDT distkey column,
supports_streaming (boolean, read-only): Suports streaming results,
automatically_run_sql_runner_snippets (boolean, read-only): Should SQL Runner snippets automatically be run,
connection_tests (Array[string], read-only): Array of names of the tests that can be run on a connection using this dialect,
supports_inducer (boolean, read-only): Is supported with the inducer (i.e. generate from sql),
can (object, read-only): Operations the current user is able to perform on this object
}
Snippet {
name (string, read-only): Name of the snippet,
label (string, read-only): Label of the snippet,
sql (string, read-only): SQL text of the snippet,
can (object, read-only): Operations the current user is able to perform on this object
}
UserPublic {
id (long, read-only): Unique Id,
first_name (string, read-only): First Name,
last_name (string, read-only): Last Name,
display_name (string, read-only): Full name for display (available only if both first_name and last_name are set),
avatar_url (string, read-only): URL for the avatar image (may be generic),
url (string, read-only): Link to get this item,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
slug true slug of query string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Create SQL Runner Query beta

POST/api/3.1/sql_queries
create_sql_query(body)

Implementation Notes

Create a SQL Runner Query.

Either the connection_name or model_name parameter MUST be provided.

Response Class

SqlQuery {
slug (string, read-only): The identifier of the SQL query,
last_runtime (float, read-only): Number of seconds this query took to run the most recent time it was run,
run_count (long, read-only): Number of times this query has been run,
browser_limit (long, read-only): Maximum number of rows this query will display on the SQL Runner page,
sql (string, read-only): SQL query text,
last_run_at (string, read-only): The most recent time this query was run,
connection (DBConnectionBase, read-only): Connection this query uses,
model_name (string, read-only): Model name this query uses,
creator (UserPublic, read-only): User who created this SQL query,
explore_url (string, read-only): Explore page URL for this SQL query,
plaintext (boolean, read-only): Should this query be rendered as plain text,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
can (object, read-only): Operations the current user is able to perform on this object
}
DBConnectionBase {
name (string, read-only): Name of the connection. Also used as the unique identifier,
dialect (Dialect, read-only): (Read-only) SQL Dialect details,
snippets (Array[Snippet], read-only): SQL Runner snippets for this connection,
can (object, read-only): Operations the current user is able to perform on this object
}
Dialect {
name (string, read-only): The name of the dialect,
label (string, read-only): The human-readable label of the connection,
supports_cost_estimate (boolean, read-only): Whether the dialect supports query cost estimates,
supports_upload_tables (boolean, read-only): Whether the dialect supports uploading tables,
persistent_table_indexes (string, read-only): PDT index columns,
persistent_table_sortkeys (string, read-only): PDT sortkey columns,
persistent_table_distkey (string, read-only): PDT distkey column,
supports_streaming (boolean, read-only): Suports streaming results,
automatically_run_sql_runner_snippets (boolean, read-only): Should SQL Runner snippets automatically be run,
connection_tests (Array[string], read-only): Array of names of the tests that can be run on a connection using this dialect,
supports_inducer (boolean, read-only): Is supported with the inducer (i.e. generate from sql),
can (object, read-only): Operations the current user is able to perform on this object
}
Snippet {
name (string, read-only): Name of the snippet,
label (string, read-only): Label of the snippet,
sql (string, read-only): SQL text of the snippet,
can (object, read-only): Operations the current user is able to perform on this object
}
UserPublic {
id (long, read-only): Unique Id,
first_name (string, read-only): First Name,
last_name (string, read-only): Last Name,
display_name (string, read-only): Full name for display (available only if both first_name and last_name are set),
avatar_url (string, read-only): URL for the avatar image (may be generic),
url (string, read-only): Link to get this item,
can (object, read-only): Operations the current user is able to perform on this object
}

Parameters

Parameter Required? Description Parameter Type Data Type
body true SQL Runner Query body
SqlQueryCreate {
connection_name (string): Name of the db connection on which to run this query,
connection_id (string): (DEPRECATED) Use connection_name instead,
model_name (string): Name of LookML Model (this or connection_id required),
sql (string): SQL query,
vis_config (object): Visualization configuration properties. These properties are typically opaque and differ based on the type of visualization used. There is no specified set of allowed keys. The values can be any type supported by JSON. A "type" key with a string value is often present, and is used by Looker to determine which visualization to present. Visualizations ignore unknown vis_config properties.,
can (object, read-only): Operations the current user is able to perform on this object
}

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}

Run SQL Runner Query beta

POST/api/3.1/sql_queries/{slug}/run/{result_format}
run_sql_query(slug, result_format, download)

Implementation Notes

Execute a SQL Runner query in a given result_format.

Response Class

  string

Parameters

Parameter Required? Description Parameter Type Data Type
slug true slug of query string string
result_format true Format of result, options are: [“json”, “json_label”, “json_detail”, “json_fe”, “csv”, “html”, “md”, “txt”, “xlsx”, “gsxml”] string string
download false Defaults to false. If set to true, the HTTP response will have content-disposition and other headers set to make the HTTP response behave as a downloadable attachment instead of as inline content. string string

Response Messages

HTTP Status Code Reason Response Model
400 Bad Request
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
404 Not Found
Error {
message (string, read-only, required): Error details,
documentation_url (string, read-only, required): Documentation link
}
422 Validation Error
ValidationError {
message (string, read-only, required): Error details,
errors (Array[ValidationErrorDetail], read-only): Error detail array,
documentation_url (string, read-only, required): Documentation link
}
ValidationErrorDetail {
field (string, read-only): Field with error,
code (string, read-only): Error code,
message (string, read-only): Error info message,
documentation_url (string, read-only, required): Documentation link
}
Top