Skip to main content
Delta Sharing is an open protocol for secure real-time exchange of large datasets. It uses a simple REST-based architecture that leverages modern cloud storage systems like S3, ADLS, and GCS to reliably transfer large datasets without requiring recipients to deploy a specific platform first.

​
Protocol Architecture

The Delta Sharing protocol defines REST APIs and message formats used by clients and servers to exchange data. It enables direct access to shared data through various tools including Pandas, Apache Spark, Tableau, and any system implementing the protocol.

​
Key Design Principles

Cloud-Native

Leverages cloud storage systems (S3, ADLS, GCS) for reliable large-scale data transfer

Secure

Uses bearer token authentication and pre-signed URLs for secure access control

Open Standard

Platform-agnostic protocol that works across different data platforms

Efficient

Supports predicate pushdown, file-level statistics, and optimized metadata queries

​
REST API Structure

All Delta Sharing REST APIs use bearer tokens for authorization. The API endpoints follow a consistent pattern: 
{prefix}/shares/{share}/schemas/{schema}/tables/{table}
Where:
  • prefix: Configurable server endpoint (e.g., https://sharing.delta.io/delta-sharing/)
  • share: The share name (case-insensitive)
  • schema: The schema name (case-insensitive)
  • table: The table name (case-insensitive)

​
Authentication

Delta Sharing uses RFC 6750 bearer token authentication. Every API request must include an authorization header: 
Authorization: Bearer {token}
The bearer token is provided to recipients through a profile file, which contains:
  • Server endpoint URL
  • Bearer token for authentication
  • Token expiration time (optional)
  • Protocol version information

​
Response Codes

All APIs return standard HTTP status codes:
StatusMeaning
200Request successful
400Malformed request
401Unauthenticated (missing or incorrect token)
403Forbidden (insufficient permissions)
404Resource not found
500Server error
Error responses include JSON with errorCode and message fields: 
{
  "errorCode": "RESOURCE_NOT_FOUND",
  "message": "The requested table does not exist"
}

​
Core API Endpoints

​
Discovery APIs

These APIs help recipients discover available resources:
GET {prefix}/sharesReturns all shares accessible to the recipient with pagination support.
{
  "items": [
    {
      "name": "vaccine_share",
      "id": "edacc4a7-6600-4fbb-85f3-a62a5ce6761f",
      "displayName": "Vaccine Share"
    }
  ],
  "nextPageToken": "..."
}
GET {prefix}/shares/{share}/schemasReturns all schemas in a share.
{
  "items": [
    {
      "name": "acme_vaccine_data",
      "share": "vaccine_share"
    }
  ]
}
GET {prefix}/shares/{share}/schemas/{schema}/tablesReturns all tables in a schema with metadata about supported access modes.
{
  "items": [
    {
      "name": "vaccine_patients",
      "schema": "acme_vaccine_data",
      "share": "vaccine_share",
      "accessModes": ["url", "dir"]
    }
  ]
}

​
Data Access APIs

GET {prefix}/shares/{share}/schemas/{schema}/tables/{table}/metadataReturns table schema, format, partition columns, and configuration.Response uses newline-delimited JSON (NDJSON) format with:
  • Protocol version information
  • Table metadata (schema, partitions, configuration)
{"protocol":{"minReaderVersion":1}}
{"metaData":{"id":"f8d5c169-3d01-4ca3-ad9e-7dc3355aedb2","format":{"provider":"parquet"},"schemaString":"..."}}
POST {prefix}/shares/{share}/schemas/{schema}/tables/{table}/queryReturns data files with optional filtering and limits.Request body supports:
  • predicateHints: SQL filter expressions
  • limitHint: Row limit hint
  • version: Time travel to specific version
  • timestamp: Time travel to specific timestamp
{
  "predicateHints": ["date >= '2021-01-01'"],
  "limitHint": 1000,
  "version": 123
}
GET {prefix}/shares/{share}/schemas/{schema}/tables/{table}/versionLightweight API to check table version for cache validation.Returns version in response header:
Delta-Table-Version: 123

​
Data Flow

The typical data access flow works as follows:
1

Authentication

Client authenticates using bearer token from profile file
2

Discovery

Client discovers available shares, schemas, and tables
3

Metadata Query

Client retrieves table schema and configuration
4

Data Query

Client requests data with optional filters and limits
5

Direct Access

Server returns pre-signed URLs; client downloads directly from cloud storage

​
Response Format

Metadata and data query responses use newline-delimited JSON (NDJSON) format: 
{"protocol":{"minReaderVersion":1}}
{"metaData":{...}}
{"file":{"url":"https://...","id":"591723a8-...","size":573}}
{"file":{"url":"https://...","id":"8b0086f2-...","size":573}}
Each line is a complete JSON object containing one of:
  • protocol: Version requirements
  • metaData: Table schema and configuration
  • file: Data file with pre-signed URL
  • add/remove/cdf: Change data feed actions
The NDJSON format enables efficient streaming of large result sets without loading the entire response into memory.

​
Protocol Versioning

The protocol uses versioning to maintain backward compatibility:
  • minReaderVersion: Minimum protocol version required to read responses
  • Currently set to 1 for all tables
  • Will increment for non-forward-compatible changes
  • Clients should validate they support the required version
{
  "protocol": {
    "minReaderVersion": 1
  }
}
When minReaderVersion increases, older clients must upgrade to continue accessing the data.

​
Capabilities Header

Clients can advertise capabilities through the delta-sharing-capabilities header: 
delta-sharing-capabilities: responseformat=delta;readerfeatures=deletionvectors
Supported capabilities:
  • responseformat: parquet (default) or delta format
  • readerfeatures: Comma-separated Delta features (e.g., deletionvectors, columnmapping)
  • includeEndStreamAction: Request end-of-stream markers
This allows servers to provide optimized responses based on client capabilities.

​
Next Steps

Data Model

Learn about the hierarchical structure of shares, schemas, and tables

Access Modes

Understand URL-based vs directory-based access patterns

Profile Files

Configure authentication with profile files

API Reference

Explore detailed API specifications

Build docs developers (and LLMs) love

Get started for freeTalk to us