The Open API specification for Synapse is now available for download!

Download Open API Spec

POST /entity/{id}/table/query/async/start

Asynchronously start a query. Use the returned job id and GET /entity/{id}/table/query/async/get to get the results of the query

Using a 'SQL like' syntax, query the current version of the rows in a single table. The following pseudo-syntax is the basic supported format:

[ALL | DISTINCT] select_expr [, select_expr ...]
FROM synapse_table_id
[WHERE where_condition]
[GROUP BY {col_name [, [col_name * ...] }
[ORDER BY {col_name [ [ASC | DESC] [, col_name [ [ASC | DESC]]}
[LIMIT row_count [ OFFSET offset ]]

Please see the following for samples: Table SQL Examples

Note: Sub-queries and joining tables is not supported.

This services depends on an index that is created/update asynchronously from table creation and update events. This means there could be short window of time when the index is inconsistent with the true state of the table. When the index is out-of-synch, then a status code of 202 (ACCEPTED) will be returned and the response body will be a TableStatus object. The TableStatus will indicates the current status of the index including how much work is remaining until the index is consistent with the truth of the table.

The 'partsMask' is an integer "mask" that can be combined into to request any desired part. As of this writing, the mask is defined as follows (see QueryBundleRequest):

  • Query Results (queryResults) = 0x1
  • Query Count (queryCount) = 0x2
  • Select Columns (selectColumns) = 0x4
  • Max Rows Per Page (maxRowsPerPage) = 0x8
  • The Table Columns (columnModels) = 0x10
  • Facet statistics for each faceted column (facetStatistics) = 0x20
  • The sum of the file sizes (sumFileSizesBytes) = 0x40
  • The last updated on date of the table (lastUpdatedOn) = 0x80
  • The SQL that combines the input query and the additional filters (combinedSql) = 0x100
  • The list of actions required to download any file that appears in the query (actionsRequired) = 0x200 (The query.selectFileColumn needs to be specified)

For example, to request all parts, the request mask value should be:
0x1 OR 0x2 OR 0x4 OR 0x8 OR 0x10 OR 0x20 OR 0x40 OR 0x80 OR 0x100 OR 0x200 = 0x3FF.

Note: The caller must have the ACCESS_TYPE.READ permission on the TableEntity to make this call.

Resource URL{id}/table/query/async/start

Resource URL Variables
{id} The ID of the TableEntity.
Resource Information
Authentication Required
Required OAuth Scopes view , download
Request Object QueryBundleRequest
Response Object AsyncJobId