Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/delta-io/delta-sharing/llms.txt

Use this file to discover all available pages before exploring further.

This API returns change data feed (CDF) information, representing row-level changes between versions of a Delta table. It records change data for UPDATE, DELETE, and MERGE operations.

​
Overview

Change Data Feed provides three metadata columns in addition to table data:
  • _change_type (String): The type of change - insert, update_preimage, update_postimage, or delete
  • _commit_version (Long): The table version containing the change
  • _commit_timestamp (Long): Unix timestamp (milliseconds) when the change was committed

​
Request

​
method
string
required
GET
​
url
string
required
{prefix}/shares/{share}/schemas/{schema}/tables/{table}/changes

​
Headers

​
Authorization
string
required
Bearer token for authentication
Authorization: Bearer {token}
​
delta-sharing-capabilities
string
Optional capabilities header for advanced features:
delta-sharing-capabilities: responseformat=delta;readerfeatures=deletionvectors
See Delta Sharing Capabilities for details.

​
URL Parameters

​
share
string
required
The share name to query. This parameter is case-insensitive.
​
schema
string
required
The schema name to query. This parameter is case-insensitive.
​
table
string
required
The table name to query. This parameter is case-insensitive.

​
Query Parameters

At least one of startingVersion or startingTimestamp must be provided.
​
startingVersion
Long
The starting version of the query (inclusive). Either this or startingTimestamp is required.
​
startingTimestamp
String
The starting timestamp in ISO8601 format (UTC timezone), e.g., 2022-01-01T00:00:00Z. Will be converted to a version created at or after this timestamp.
​
endingVersion
Long
The ending version of the query (inclusive). If not provided, uses the latest table version.
​
endingTimestamp
String
The ending timestamp in ISO8601 format (UTC timezone). Will be converted to a version created at or before this timestamp.
​
includeHistoricalMetadata
Boolean
If true, return historical metadata seen in the delta log. Useful for streaming clients to check schema compatibility.Default: false

​
Response

​
Headers

​
Content-Type
string
Content-Type: application/x-ndjson; charset=utf-8
​
Delta-Table-Version
Long
The starting version of files in the response

​
Response Body

The response is newline-delimited JSON (NDJSON) with the following structure:
​
protocol
object
required
First line: Protocol version information
{
  "protocol": {
    "minReaderVersion": 1
  }
}
​
metaData
object
required
Second line: Table metadata (current and optionally historical if includeHistoricalMetadata=true)
​
add
object
Change data: File additions
​
cdf
object
Change data feed files (changes stored in _change_data directory)
​
remove
object
Change data: File removals

​
Example Request

curl -X GET \
  '{prefix}/shares/share_name/schemas/schema_name/tables/table_name/changes?startingVersion=0&endingVersion=2' \
  -H 'Authorization: Bearer {token}'

​
Example Response

HTTP/2 200
content-type: application/x-ndjson; charset=utf-8
delta-table-version: 0

{"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"],"configuration":{"enableChangeDataFeed":"true"}}}
{"add":{"url":"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table_cdf/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}}","timestamp":1652140000000,"version":0}}
{"cdf":{"url":"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table_cdf/_change_data/date%3D2021-04-28/part-00000-591723a8.parquet?...","id":"591723a8-6a27-4240-a90e-57426f4736d2","partitionValues":{"date":"2021-04-28"},"size":689,"timestamp":1652141000000,"version":1}}
{"remove":{"url":"https://<s3-bucket-name>.s3.us-west-2.amazonaws.com/delta-exchange-test/table_cdf/date%3D2021-04-28/part-00000-8b0086f2.parquet?...","id":"8b0086f2-7b27-4935-ac5a-8ed6215a6640","partitionValues":{"date":"2021-04-28"},"size":573,"timestamp":1652142000000,"version":2}}

​
Using Timestamps

curl -X GET \
  '{prefix}/shares/share/schemas/schema/tables/table/changes?startingVersion=5&endingVersion=10' \
  -H 'Authorization: Bearer {token}'

​
Error Responses

​
Change Types

The _change_type column in CDF files indicates the type of operation:
  • insert: New row added to the table
  • update_preimage: Row values before an update
  • update_postimage: Row values after an update
  • delete: Row removed from the table
Change Data Feed must be enabled on the table (enableChangeDataFeed = true in table configuration) for this API to work.