> ## Documentation Index > Fetch the complete documentation index at: https://developer.voyado.com/llms.txt > Use this file to discover all available pages before exploring further. # Delta Share Delta Sharing is an open protocol for the secure exchange of large amounts of data. Its advantage is that it allows you to download only the changes and not the whole dataset every time, saving time and bandwidth. ## Delta Share in Engage In Engage, you can get direct access to raw data using the open Delta Sharing protocol. Unlike BI Export, data is not pre-processed or aggregated. Instead, each Engage domain team publishes their own data products, and you connect to them directly from your own data infrastructure. Delta Sharing in Engage is designed for customers who want full flexibility to work with raw data in their own warehouse, update in almost real-time, and model the data to their own analytical needs. ## What is a data product? A **data product** is a packaged, domain-specific dataset published through Delta Share. Unlike a BI Export (which is a single flat file per entity), a data product groups together multiple related tables around one business concept. ## The two data products Delta Share offers two categories of data products: * **Raw data products**: Domain data with minimal processing (schema, validation, basic cleaning). Included at no additional cost. * **Analytical data products**: Pre-modelled data using a star schema (fact and dimension tables), designed for direct analytical use. Subject to a separate fee. | | **Raw data products** | **Analytical data products** | | :----------------- | :------------------------------------------ | :------------------------------------ | | **Data model** | As-is from the source module | Star schema (fact + dimension tables) | | **Transformation** | Minimal: schema, validation, basic cleaning | Pre-modelled and analysis-ready | | **Best for** | Data engineers building pipelines | Analysts querying data directly | | **Cost** | Included with Delta Share | Separate fee, contact your CSM or AM | The two kinds of data products wil now be considered separately. ### Raw data products Raw data products provide domain-specific data from each Engage module. The data is shared with minimal processing (Voyado adds schema definitions, validate the structure, and perform basic cleaning) but there is no enrichment, transformation, or cross-domain consolidation applied. Updates run in batches 2-4 times per day (with plans to make it more configurable in the future). Raw data products are *included at no additional cost* with Delta Share. Here is the current list of raw data products: Core engagement data across Engage. Purchase and transaction data: receipts, line items, returns, and related structures. Message delivery and interaction data: sendouts, delivery status, opens, clicks. Contact record data: core contact attributes and related fields. Customer reviews and feedback: review summaries, detailed reviews, and comments. Dun & Bradstreet household enrichment data with demographic and lifestyle attributes. The data products you have access to depends both on your Engage configuration *and* what has been enabled for sharing. ### Analytical data products Analytical data products deliver pre-modelled, analysis-ready data through Delta Share. Unlike raw data products, the data is structured using a **star schema** with clearly defined fact and dimension tables. This means you can query it directly for reporting and analytics without needing to build your own transformation layer. Analytical data products are subject to a separate fee. Contact your Voyado CSM or account manager for details on availability and pricing. #### Starfish Starfish is used in Engage's analytical data products. It is a modelled analytical data product built on a star schema, containing fact tables (such as transactions, message events) and dimension tables (such as contacts, stores, products) all designed for direct use in BI tools and analytical queries. Starfish removes the need to construct your own dimensional model from raw data. ## Accessing Delta Share This process varies depending on which kind of data products you are using. * **Raw data products:** You can set up these shares and receive credentials yourself using Config Hub. The guide here explains it in greater detail: * **Analytical data products (Starfish):** Since this option is a paid offering, credentials are provisioned by Voyado and provided by your CSM or account manager after purchase. ## How to connect Once you have access, you'll receive an activation link. Opening this link lets you download a `.share` credentials file, which looks something like this: ```json theme={null} { "shareCredentialsVersion": 1, "bearerToken": "fdij0238d209f94h2...", "endpoint": "https://northeurope-c2.azuredatabricks.net/api/2.0/...", "expirationTime": "9999-12-31T23:59:59.999Z" } ``` The `bearerToken` is sensitive information, so treat it like you would an API key or a password. Do *not* commit it to source control. Delta Share works with any client that implements the Delta Sharing protocol: | **Tool** | **How to connect** | | :------------------ | :----------------------------------------------------------- | | **Power BI** | Get Data → Delta Sharing → paste server URL and bearer token | | **Tableau** | Install "Delta Sharing by Databricks" from Tableau Exchange | | **Spark (PySpark)** | Use `format("deltasharing")` with the profile path | | **pandas (Python)** | Use the `delta_sharing` library with `load_as_pandas()` | | **Other** | Any client implementing the Delta Sharing REST protocol | ```python theme={null} table_url = "/path/to/profile.share#.." df = spark.read.format("deltasharing").load(table_url) ``` ```python theme={null} cdf = (spark.read .format("deltasharing") .option("readChangeFeed", "true") .option("startingTimestamp", "2025-08-01 00:00:00") .load(table_url) ) ``` ```python theme={null} import delta_sharing as ds pdf = ds.load_as_pandas(table_url) ``` ## Updating data Delta Share allows customers to incrementally retrieve changes to their data and store those changes in their own data warehouse or similar storage solution. This is achieved by storing every batch of new or modified records with `_commit_version` tag. Consumers can then download all data associated with a specific commit version. When new or updated data is added to Delta Share, that record is given the value “insert” in the `_change_type` column. A record with `_change_type` value of "insert" simply means data which is new or updated. Delta Share uses append mode, meaning that every update adds new records instead of replacing existing ones. * The column `_commit_version` indicates which version the record belongs to. * The column `_commit_timestamp` shows when the record was added. _commit_timestamp Only download the changes made since your last sync. ## Deleting data In January 2026 the "delete" pattern was introduced. Depending on how consumers of Delta Share have implemented their integrations, this change may require adjustments on their side. Data can now have a `_change_type` value of "delete". This means the row is older than 30 days and will be removed. This value will be automatically generated for any row where the `import_date_time` is older than 30 days. A `_change_type` value of "delete" does not modify the original data. All fields remain unchanged. Instead, it serves as a technical log entry indicating that the corresponding row will be removed from Delta Share. Consumers of Delta Share may choose to ignore these "delete" records. ## Extra information Here is some extra information on Delta Share. ### Key concepts * **Share**: A logical grouping of data for a recipient. In Engage, each recipient has access to one share. * **Schema**: A grouping of tables within a share. Each Engage share contains one schema. * **Table**: A dataset made up of one or more files, in Parquet format. * **Recipient**: A principal with a bearer token. One recipient per share simplifies revocation and auditing. Data is stored in *Apache Parquet* format with a Delta metadata layer. Records are appended — not overwritten — so multiple versions of a record may exist. Use the `import_date_time` column to identify the most recent version. ### Best practices When implementing Delta Sharing here are some best practices to keep in mind: * Keep shares small and purposeful: one share per product, avoid “kitchen sink” shares * Schema contracts: version breaking changes (for example `dp\orders\v2`) * Select only columns you need; apply filters for predicate pushdown * For Power BI, mind the row limit behavior in Power Query * Incremental loads: prioritise CDF over re-reading entire tables * Security: favor OIDC federation over long-lived bearer tokens where possible (better rotation, MFA) * Auditing: one recipient per share simplifies revocation and tracking ### Rate limit The rate limit for Delta Share is 10 requests per second. Exceeding this will returns *HTTP 429*. Stagger your requests when querying multiple tables in parallel. ### Data retention Delta table history is retained for *30 days*. After that, older versions are removed and time-travel reads are no longer possible. If you need long-term historical access, copy or snapshot the data locally. ### FAQ Here are collected some frequently asked questions on Delta Share in Engage. You get the latest full snapshot of the table — all currently active records. Historical data outside the 30-day retention window is not included. The change feed only covers the 30-day retention window. Versions older than 30 days are cleaned up automatically and cannot be retrieved afterward. This typically means a full export or reset was performed in Engage, clearing all previous table versions. After a reset, queries must start from the latest (max) version. All data from that point onward continues to be available. Yes — they serve different purposes and can be used in parallel. See the decision guide for guidance. Using the "query" option returns **all data currently available in the Delta Share**. In other words, the **latest full snapshot** of that table. It does *not* include all historical data, only what's active right now. Some Delta setups allow “time travel” to older versions of the data, but this only works if history sharing is enabled for that table. Old versions are automatically cleaned up according to the retention policy (for Voyado, that's 30 days).\ This means you only have access to what's currently part of the share and not every piece of data stored in Engage. Yes. Delta Share tables follow a **retention policy**. In Voyado's case, **data older than 30 days** is removed automatically. So, when you use a "query" you're getting the most recent snapshot. Data outside of the retention window isn't available. The "changes" option provides **incremental updates,** meaning only the rows that were added, modified, or deleted between table versions. It works through Delta's Change Data Feed (CDF), so the feature must be enabled for that table. Each update includes metadata like: * \_change\_type * \_commit\_version * \_commit\_timestamp The versions you can access depend on the **retention window**, not the number of versions or files. Once versions are older than 30 days, they're no longer accessible. If you try to query a starting or ending version outside that 30-day window, no data will be returned. Availability is based solely on time, not on how many versions or files exist. Once data versions pass the 30-day retention threshold, they're cleaned up automatically. There's no way to retrieve them afterward. If a table shows no version history, it typically means: * Change Data Feed (CDF) or version tracking is not enabled for that share, or * All historical versions have been cleaned up by the retention policy. In such cases, you'll only have access to the **latest snapshot**, with no historical data or changes available.