Query the table

curl --request POST \
  --url http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query \
  --header 'Content-Type: application/json' \
  --data '
{
  "predicateHints": [
    "col = 123"
  ],
  "jsonPredicateHints": {
    "children": "<string>",
    "name": "<string>",
    "value": "<string>",
    "valueType": "<string>"
  },
  "limitHint": 1000,
  "version": 1005,
  "timestamp": "yyyy-[m]m-[d]d hh:mm:ss[.f...]",
  "startingVersion": 1000,
  "endingVersion": 1000
}
'

import requests

url = "http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query"

payload = {
    "predicateHints": ["col = 123"],
    "jsonPredicateHints": {
        "children": "<string>",
        "name": "<string>",
        "value": "<string>",
        "valueType": "<string>"
    },
    "limitHint": 1000,
    "version": 1005,
    "timestamp": "yyyy-[m]m-[d]d hh:mm:ss[.f...]",
    "startingVersion": 1000,
    "endingVersion": 1000
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    predicateHints: ['col = 123'],
    jsonPredicateHints: {
      children: '<string>',
      name: '<string>',
      value: '<string>',
      valueType: '<string>'
    },
    limitHint: 1000,
    version: 1005,
    timestamp: 'yyyy-[m]m-[d]d hh:mm:ss[.f...]',
    startingVersion: 1000,
    endingVersion: 1000
  })
};

fetch('http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8000",
  CURLOPT_URL => "http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'predicateHints' => [
        'col = 123'
    ],
    'jsonPredicateHints' => [
        'children' => '<string>',
        'name' => '<string>',
        'value' => '<string>',
        'valueType' => '<string>'
    ],
    'limitHint' => 1000,
    'version' => 1005,
    'timestamp' => 'yyyy-[m]m-[d]d hh:mm:ss[.f...]',
    'startingVersion' => 1000,
    'endingVersion' => 1000
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query"

	payload := strings.NewReader("{\n  \"predicateHints\": [\n    \"col = 123\"\n  ],\n  \"jsonPredicateHints\": {\n    \"children\": \"<string>\",\n    \"name\": \"<string>\",\n    \"value\": \"<string>\",\n    \"valueType\": \"<string>\"\n  },\n  \"limitHint\": 1000,\n  \"version\": 1005,\n  \"timestamp\": \"yyyy-[m]m-[d]d hh:mm:ss[.f...]\",\n  \"startingVersion\": 1000,\n  \"endingVersion\": 1000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query")
  .header("Content-Type", "application/json")
  .body("{\n  \"predicateHints\": [\n    \"col = 123\"\n  ],\n  \"jsonPredicateHints\": {\n    \"children\": \"<string>\",\n    \"name\": \"<string>\",\n    \"value\": \"<string>\",\n    \"valueType\": \"<string>\"\n  },\n  \"limitHint\": 1000,\n  \"version\": 1005,\n  \"timestamp\": \"yyyy-[m]m-[d]d hh:mm:ss[.f...]\",\n  \"startingVersion\": 1000,\n  \"endingVersion\": 1000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"predicateHints\": [\n    \"col = 123\"\n  ],\n  \"jsonPredicateHints\": {\n    \"children\": \"<string>\",\n    \"name\": \"<string>\",\n    \"value\": \"<string>\",\n    \"valueType\": \"<string>\"\n  },\n  \"limitHint\": 1000,\n  \"version\": 1005,\n  \"timestamp\": \"yyyy-[m]m-[d]d hh:mm:ss[.f...]\",\n  \"startingVersion\": 1000,\n  \"endingVersion\": 1000\n}"

response = http.request(request)
puts response.read_body

"{\"protocol\":{\"minReaderVersion\":1}}\n{\"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\"]}}\n{\"file\":{\"url\":\"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-8b0086f2-7b27-4935-ac5a-8ed6215a6640.c000.snappy.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210501T010516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=AKIAISZRDL4Q4Q7AIONA%2F20210501%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=97b6762cfd8e4d7e94b9d707eff3faf266974f6e7030095c1d4a66350cfd892e\",\"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}}\"}}\n{\"file\":{\"url\":\"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-591723a8-6a27-4240-a90e-57426f4736d2.c000.snappy.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210501T010516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=AKIAISZRDL4Q4Q7AIONA%2F20210501%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=0f7acecba5df7652457164533a58004936586186c56425d9d53c52db574f6b62\",\"id\":\"591723a8-6a27-4240-a90e-57426f4736d2\",\"partitionValues\":{\"date\":\"2021-04-28\"},\"size\":573,\"stats\":\"{\\\"numRecords\\\":1,\\\"minValues\\\":{\\\"eventTime\\\":\\\"2021-04-28T23:33:48.719Z\\\"},\\\"maxValues\\\":{\\\"eventTime\\\":\\\"2021-04-28T23:33:48.719Z\\\"},\\\"nullCount\\\":{\\\"eventTime\\\":0}}\"}}\n"

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

POST

{share}

schemas

{schema}

tables

{table}

query

Query the table

curl --request POST \
  --url http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query \
  --header 'Content-Type: application/json' \
  --data '
{
  "predicateHints": [
    "col = 123"
  ],
  "jsonPredicateHints": {
    "children": "<string>",
    "name": "<string>",
    "value": "<string>",
    "valueType": "<string>"
  },
  "limitHint": 1000,
  "version": 1005,
  "timestamp": "yyyy-[m]m-[d]d hh:mm:ss[.f...]",
  "startingVersion": 1000,
  "endingVersion": 1000
}
'

import requests

url = "http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query"

payload = {
    "predicateHints": ["col = 123"],
    "jsonPredicateHints": {
        "children": "<string>",
        "name": "<string>",
        "value": "<string>",
        "valueType": "<string>"
    },
    "limitHint": 1000,
    "version": 1005,
    "timestamp": "yyyy-[m]m-[d]d hh:mm:ss[.f...]",
    "startingVersion": 1000,
    "endingVersion": 1000
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    predicateHints: ['col = 123'],
    jsonPredicateHints: {
      children: '<string>',
      name: '<string>',
      value: '<string>',
      valueType: '<string>'
    },
    limitHint: 1000,
    version: 1005,
    timestamp: 'yyyy-[m]m-[d]d hh:mm:ss[.f...]',
    startingVersion: 1000,
    endingVersion: 1000
  })
};

fetch('http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8000",
  CURLOPT_URL => "http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'predicateHints' => [
        'col = 123'
    ],
    'jsonPredicateHints' => [
        'children' => '<string>',
        'name' => '<string>',
        'value' => '<string>',
        'valueType' => '<string>'
    ],
    'limitHint' => 1000,
    'version' => 1005,
    'timestamp' => 'yyyy-[m]m-[d]d hh:mm:ss[.f...]',
    'startingVersion' => 1000,
    'endingVersion' => 1000
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query"

	payload := strings.NewReader("{\n  \"predicateHints\": [\n    \"col = 123\"\n  ],\n  \"jsonPredicateHints\": {\n    \"children\": \"<string>\",\n    \"name\": \"<string>\",\n    \"value\": \"<string>\",\n    \"valueType\": \"<string>\"\n  },\n  \"limitHint\": 1000,\n  \"version\": 1005,\n  \"timestamp\": \"yyyy-[m]m-[d]d hh:mm:ss[.f...]\",\n  \"startingVersion\": 1000,\n  \"endingVersion\": 1000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query")
  .header("Content-Type", "application/json")
  .body("{\n  \"predicateHints\": [\n    \"col = 123\"\n  ],\n  \"jsonPredicateHints\": {\n    \"children\": \"<string>\",\n    \"name\": \"<string>\",\n    \"value\": \"<string>\",\n    \"valueType\": \"<string>\"\n  },\n  \"limitHint\": 1000,\n  \"version\": 1005,\n  \"timestamp\": \"yyyy-[m]m-[d]d hh:mm:ss[.f...]\",\n  \"startingVersion\": 1000,\n  \"endingVersion\": 1000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8000/api/v1/shares/{share}/schemas/{schema}/tables/{table}/query")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"predicateHints\": [\n    \"col = 123\"\n  ],\n  \"jsonPredicateHints\": {\n    \"children\": \"<string>\",\n    \"name\": \"<string>\",\n    \"value\": \"<string>\",\n    \"valueType\": \"<string>\"\n  },\n  \"limitHint\": 1000,\n  \"version\": 1005,\n  \"timestamp\": \"yyyy-[m]m-[d]d hh:mm:ss[.f...]\",\n  \"startingVersion\": 1000,\n  \"endingVersion\": 1000\n}"

response = http.request(request)
puts response.read_body

"{\"protocol\":{\"minReaderVersion\":1}}\n{\"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\"]}}\n{\"file\":{\"url\":\"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-8b0086f2-7b27-4935-ac5a-8ed6215a6640.c000.snappy.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210501T010516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=AKIAISZRDL4Q4Q7AIONA%2F20210501%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=97b6762cfd8e4d7e94b9d707eff3faf266974f6e7030095c1d4a66350cfd892e\",\"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}}\"}}\n{\"file\":{\"url\":\"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-591723a8-6a27-4240-a90e-57426f4736d2.c000.snappy.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210501T010516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=AKIAISZRDL4Q4Q7AIONA%2F20210501%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=0f7acecba5df7652457164533a58004936586186c56425d9d53c52db574f6b62\",\"id\":\"591723a8-6a27-4240-a90e-57426f4736d2\",\"partitionValues\":{\"date\":\"2021-04-28\"},\"size\":573,\"stats\":\"{\\\"numRecords\\\":1,\\\"minValues\\\":{\\\"eventTime\\\":\\\"2021-04-28T23:33:48.719Z\\\"},\\\"maxValues\\\":{\\\"eventTime\\\":\\\"2021-04-28T23:33:48.719Z\\\"},\\\"nullCount\\\":{\\\"eventTime\\\":0}}\"}}\n"

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

Path Parameters

Named share for finding the named schema

schema

string

required

Named schema for finding the named table

table

string

required

Named table

Query Parameters

startingTimestamp

string

Starting Timestamp

Body

application/json

predicateHints

string[]

a list of SQL boolean expressions using a restricted subset of SQL, in a JSON array. When it’s present, the server will use the provided predicates as a hint to apply the SQL predicates on the returned files. Filtering files based on the SQL predicates is BEST EFFORT. The server may return files that don’t satisfy the predicates. If the server fails to parse one of the SQL predicates, or fails to evaluate it, the server may skip it. Predicate expressions are conjunctive (AND-ed together). When it’s absent, the server will return all of files in the table. This will be deprecated once all the client and server implementation move to using jsonPredicateHints below.

Example:

["col = 123"]

jsonPredicateHints

object

query predicates on partition columns specified using a structured JSON format. When it’s present, the server will try to use the predicates to filter table's files, which could boost query performance. As with predicateHints, this filtering is BEST EFFORT. The server may return files that don’t satisfy the predicates. If the server encounters any errors during predicate processing (for example, invalid syntax or non existing columns), it will skip filtering and return all the files. When it’s absent, the server will return all the files in the table.

Show child attributes

limitHint

integer

It’s a hint from the client to tell the server how many rows the client plans to read. The server can use this hint to return only some files by using the stats in the Delta transaction logs. For example, when running SELECT * FROM table LIMIT 1000, the client can send limit=1000 to the server

Example:

1000

version

integer

an optional version number. If set, will return files as of the specified version of the table. This is only supported on tables with history sharing enabled.

Example:

1005

timestamp

string

an optional timestamp string in the Timestamp Format,. If set, will return files as of the table version corresponding to the specified timestamp. This is only supported on tables with history sharing enabled.

Example:

"yyyy-[m]m-[d]d hh:mm:ss[.f...]"

startingVersion

integer

an optional version number. If set, will return all data change files since startingVersion, inclusive, including historical metadata if seen in the delta log.

Example:

1000

endingVersion

integer

an optional version number, only used if startingVersion is set. If set, the server can use it as a hint to avoid returning data change files after endingVersion. This is not enforcement. Hence, when sending the endingVersion parameter, the client should still handle the case that it may receive files after endingVersion.

Example:

1000

Response

A sequence of JSON strings containing the table protocol, metadata, and then a number of lines for each file in the table.

The response is of type string.

Example:

"{\"protocol\":{\"minReaderVersion\":1}}\n{\"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\"]}}\n{\"file\":{\"url\":\"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-8b0086f2-7b27-4935-ac5a-8ed6215a6640.c000.snappy.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210501T010516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=AKIAISZRDL4Q4Q7AIONA%2F20210501%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=97b6762cfd8e4d7e94b9d707eff3faf266974f6e7030095c1d4a66350cfd892e\",\"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}}\"}}\n{\"file\":{\"url\":\"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table2/date%3D2021-04-28/part-00000-591723a8-6a27-4240-a90e-57426f4736d2.c000.snappy.parquet?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210501T010516Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=AKIAISZRDL4Q4Q7AIONA%2F20210501%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Signature=0f7acecba5df7652457164533a58004936586186c56425d9d53c52db574f6b62\",\"id\":\"591723a8-6a27-4240-a90e-57426f4736d2\",\"partitionValues\":{\"date\":\"2021-04-28\"},\"size\":573,\"stats\":\"{\\\"numRecords\\\":1,\\\"minValues\\\":{\\\"eventTime\\\":\\\"2021-04-28T23:33:48.719Z\\\"},\\\"maxValues\\\":{\\\"eventTime\\\":\\\"2021-04-28T23:33:48.719Z\\\"},\\\"nullCount\\\":{\\\"eventTime\\\":0}}\"}}\n"

Last modified on August 10, 2026

⌘I