Databricks (Delta Sharing) - Dema.ai documentation

Supported data types

Inventory

Stock levels

Logistics

Shipping & fulfillment costs

Orders

Customer transactions

Product Attributes

Product metadata & descriptions

Returns

Returns, with or without an order reference

Prerequisites

Before setting up the Databricks integration, ensure you have:

A Databricks workspace with Delta Sharing enabled
Tables in Unity Catalog containing your data, with columns matching our schema
A share containing the relevant tables that can be shared externally

If your workspace uses Unity Catalog, you can share your tables with Dema’s Databricks workspace instead of sending an open Delta Sharing token. Contact your Customer Success Manager for Dema’s sharing identifier. Dema mounts your share as a catalog and reads <catalog>.<schema>.<table> directly, so you don’t provide any bearer token or credentials.For incremental (changes) reads, enable Change Data Feed on the source table and add the table to the share with history. When Dema checks the connection, it confirms that the configured table is reachable.Instead of shareName, the table configuration uses the catalog name Dema mounted your share as:

Connection

{
  "catalog": "example_catalog",
  "schema": "example_schema",
  "table": "example_table"
}

Each data type above is typically configured as its own integration, reading from its own table — set up as many or as few as you need, each pointed at its own shareName/schema/table. There are two exceptions: the legacy Inventory V1 format combines stock levels and product attributes into a single table (see Version 1 (Legacy)), and returns can either use their own dedicated table (see Returns) or be recorded directly within the orders table (see Return fields within orders).

Good to know

COGS priority

Storefront assignment

If you operate multiple storefronts, include EXTERNAL_STOREFRONT_ID in your data for per-row storefront assignment.

Merchant mappings

Step-by-step integration guide

Create a Delta Share

In your Databricks workspace, create a Delta Share containing the tables you want to integrate. Ensure the tables have columns matching our schema below.Refer to the Databricks Delta Sharing documentation for details on creating and managing shares.

Share credentials

Provide the following to your Customer Success Manager:

Send the information via secure password sharing.

Delta Sharing credentials:

Credentials

{
  "bearerToken": "<your-token>",
  "endpoint": "https://<workspace-url>/api/2.0/delta-sharing",

  // optional
  "icebergEndpoint": "https://<workspace-url>/api/2.0/unity-catalog/iceberg",
  "expirationTime": "2026-12-31T23:59:59.999Z"
}

Table configuration:

Connection

{
  "shareName": "example_share",
  "schema": "example_schema",
  "table": "example_table"
}

Specifying data tables and schema

Ensure each table aligns with our schema. Columns must be named according to the column names specified in the schema below. This is crucial for accurate data integration.

Finalizing integration

After setting up the share and ensuring data mapping accuracy, our team will finalize the integration process, enabling data flow from Databricks into our platform.

Multiple values Some fields allow multiple values. These fields can be added as column of Array type, like ["value1", "value2", "value3"].

Data schema

Inventory

Version 2 (Current)
Version 1 (Legacy)

The current inventory format — only the stock-level and cost fields.

Fields

required

Logistics

Shipping and fulfillment costs associated with orders.

The system supports both outbound shipments to customers and return shipments from customers.

Fields

Orders

Customer transaction data including order details and line items. See COGS priority for how cost values are resolved.

How order data should be structured

Each row represents a unique order line, identified by the combination of ORDER_ID, PRODUCT_ID, and VARIANT_NO.

Requirement	Description
Unique rows	Each row must have a unique `ORDER_ID-PRODUCT_ID-VARIANT_NO` combination
Quantity handling	If multiple items of the same variant were bought, aggregate them using `QUANTITY`
Tax inclusion	All prices should include tax
Header repetition	Order header fields (like `ORDER_ID`, `CURRENCY`, `TOTAL`) must be repeated for every line item in the same order
Updates	When an order changes, update the existing rows for that `ORDER_ID` in place and set `UPDATED_AT` to the current timestamp. Do not insert duplicate rows — each `ORDER_ID`–`PRODUCT_ID`–`VARIANT_NO` combination must remain unique
Line-level overrides	Line-level fields override their order-level equivalents when set: `STATUS_LINE` overrides `STATUS`, and `SHIPPING_PROVIDER_LINE` overrides `SHIPPING_PROVIDER`
Storefront mapping	To map data to a specific storefront, fill out `EXTERNAL_STOREFRONT_ID` and provide us with info about your existing storefronts, see Storefront assignment

Order header fields

Required:

Order line fields

Required:

Return fields (within orders)

Include these fields to record returns directly in your orders table.Required:Optional:

Custom attributes

Order header level:Order line level:

Product Attributes

Product metadata including names, categories, and descriptive attributes for your catalog.

Required fields

Optional fields

Custom attributes

Returns

Return lines read from their own dedicated table. This is an alternative to the Return fields (within orders) accordion above — use whichever fits how your returns data is produced; you don’t need both. Each row is handled according to the identifier it carries: a RETURN_ID makes it an unreferenced return (even if the row also has an ORDER_ID), an ORDER_ID alone makes it a referenced return. Rows with neither are skipped. Both shapes can share one table.

Referenced returns
Unreferenced returns

Returns that link back to an existing order, which supplies the pricing.

Each row should have a unique ORDER_ID-VARIANT_NO combination.

Fields

Required:

required

Format:
Example:

Optional:

Returns with no order to link to — a RETURN_ID takes the place of the ORDER_ID. Since there is no order to inherit pricing from, these rows also carry the line economics you would put on an order line. There is no order date either: RETURNED_AT dates the return, and there is no CREATED_AT column.

Each row should have a unique RETURN_ID-VARIANT_NO combination.

Fields

Required:

required

Format:
Example:

required

Format:
Example:

required

Format:
Example:

Tax fields (one required):Optional:

Format:
Example:
Fallback: when QUANTITY is missing or empty, the returned quantity is used — RETURNED_QUANTITY_DECIMAL, then RETURNED_QUANTITY.

Format:
Example:
Default: UNKNOWN

Example:

Format:
Example:
Requires: COGS_CURRENCY

Format:
Example:

Troubleshooting and support

For common issues and solutions, contact our support team directly for assistance.

Additional resources

Databricks Delta Sharing documentation: Databricks Documentation

​Supported data types

Inventory

Logistics

Orders

Product Attributes

Returns

​Prerequisites

​Good to know

​Merchant mappings

​Step-by-step integration guide

​Data schema

​Inventory

​Logistics

​Orders

​Product Attributes

​Returns

​Troubleshooting and support

​Additional resources

Supported data types

Prerequisites

Good to know

Merchant mappings

Step-by-step integration guide

Data schema

Inventory

Logistics

Orders

Product Attributes

Returns

Troubleshooting and support

Additional resources