This is the primary API for reading data from a Delta Sharing table. It supports filtering, pagination hints, time travel, and streaming queries.
Request {prefix}/shares/{share}/schemas/{schema}/tables/{table}/query
Bearer token for authentication Authorization: Bearer {token}
Content-Type: application/json; charset=utf-8
delta-sharing-capabilities
Optional capabilities header for advanced features: delta-sharing-capabilities: responseformat=delta;readerfeatures=deletionvectors
See Delta Sharing Capabilities for details. URL Parameters The share name to query. This parameter is case-insensitive.
The schema name to query. This parameter is case-insensitive.
The table name to query. This parameter is case-insensitive.
Request Body List of SQL boolean expressions for filtering files. Applied as best-effort hints.
Uses a restricted subset of SQL
Expressions are AND-ed together
Server may return files that don’t satisfy predicates
Will be deprecated in favor of jsonPredicateHints Example: [ "date >= '2021-01-01'" , "date <= '2021-01-31'" ]
Query predicates on partition columns in structured JSON format. Best-effort filtering hint.
Hint for the maximum number of rows the client plans to read. Server may use file statistics to return a subset of files. Example: Set to 1000 for SELECT * FROM table LIMIT 1000
Table version number for time travel queries. Returns files as of the specified version. Only supported on tables with history sharing enabled.
Timestamp string in ISO8601 format (UTC timezone). Returns files corresponding to the table version at this timestamp. Format: 2022-01-01T00:00:00Z Only supported on tables with history sharing enabled.
Starting version (inclusive) for streaming queries. Returns all data change files since this version, including historical metadata. Used for Delta Sharing Structured Streaming support.
Optional ending version hint when startingVersion is set. Not enforced - client should handle files beyond this version.
Response Content-Type: application/x-ndjson; charset=utf-8
Without time travel: Current table version
With time travel: Starting version of returned files
Response Body The response is a sequence of newline-delimited JSON (NDJSON) objects:
First line: Protocol version information { "protocol" : { "minReaderVersion" : 1 } }
Second line: Table metadata including schema Unique table identifier (UUID)
File format information (typically {"provider": "parquet"})
JSON-encoded Delta Lake schema
Array of partition column names
Table configuration properties
Subsequent lines: Data file objects (for snapshot queries) Pre-signed URL for downloading the file
Map of partition column names to values
JSON-encoded statistics (numRecords, minValues, maxValues, nullCount)
For streaming queries (startingVersion set): Change data files Pre-signed URL for the file
Commit timestamp in milliseconds
Table version for this change
Example: Snapshot Query curl -X POST \ '{prefix}/shares/share_name/schemas/schema_name/tables/table_name/query' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "predicateHints": [ "date >= '"'"'2021-01-01'"'"'", "date <= '"'"'2021-01-31'"'"'" ], "limitHint": 1000, "version": 123 }'
Response HTTP/2 200 content-type: application/x-ndjson; charset=utf-8 delta-table-version: 123
{ "protocol" :{ "minReaderVersion" : 1 }} { "metaData" :{ "id" : "f8d5c169-3d01-4ca3-ad9e-7dc3355aedb2" , "format" :{ "provider" : "parquet" }, "schemaString" : "{ \" type \" : \" struct \" , \" fields \" :[{ \" name \" : \" eventTime \" , \" type \" : \" timestamp \" , \" nullable \" :true, \" metadata \" :{}},{ \" name \" : \" date \" , \" type \" : \" date \" , \" nullable \" :true, \" metadata \" :{}}]}" , "partitionColumns" :[ "date" ]}} { "file" :{ "url" : "https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-8b0086f2.parquet?..." , "id" : "8b0086f2-7b27-4935-ac5a-8ed6215a6640" , "partitionValues" :{ "date" : "2021-04-28" }, "size" : 573 , "stats" : "{ \" numRecords \" :1, \" minValues \" :{ \" eventTime \" : \" 2021-04-28T23:33:57.955Z \" }, \" maxValues \" :{ \" eventTime \" : \" 2021-04-28T23:33:57.955Z \" }, \" nullCount \" :{ \" eventTime \" :0}}" }}
Example: Streaming Query curl -X POST \ '{prefix}/shares/share_name/schemas/schema_name/tables/table_name/query' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{"startingVersion": 1}'
Error Responses The request is malformed. { "errorCode" : "string" , "message" : "string" }
The bearer token is missing or incorrect. { "errorCode" : "string" , "message" : "string" }
The request is forbidden from being fulfilled. { "errorCode" : "string" , "message" : "string" }
The requested resource does not exist. { "errorCode" : "string" , "message" : "string" }
Show 500 - Internal Server Error
The request is not handled correctly due to a server error. { "errorCode" : "string" , "message" : "string" }
Best-effort filtering : Both predicateHints and limitHint are hints, not guarantees. The client must always apply additional filtering and limiting if needed. If both are present, the server applies predicates first, then limits.
Empty request : Provide an empty JSON object {} when no parameters are needed.
