Object definition overrides for the Openflow Connector for Shopify¶

This topic describes the Object Definitions Override parameter in detail, including the full schema, promoted column and child field definitions, and a complete example.

The Object Definitions Override parameter accepts a JSON array of object definitions. Each definition can add a new object type or fully replace an existing catalog entry.

Object definition schema¶

The following fields are supported in each object definition:

Promoted columns¶

Promoted columns extract specific values from the raw JSON payload into dedicated typed columns in the destination table. This makes frequently queried fields available as first-class Snowflake columns for efficient filtering and aggregation.

Each promoted column has the following fields:

Child fields¶

Child field definitions extract nested connections (such as order line items) into separate Snowflake tables. Each child table includes a __PARENT_ID column linking records back to the parent.

Each child field has the following fields:

Union types and GID routing¶

When a query root returns a union type, the records in the Shopify Bulk API response carry GID types that correspond to the concrete wrapper node types, not the query root name or the GraphQL union type name. The connector’s PartitionShopifyByObject processor routes records by GID type, so if the GID type isn’t registered in gidTypeName or additionalGidTypeNames, records are routed to failure.

For example, the discountNodes query root returns the Discount union. The records in the response carry GID types DiscountCodeNode and DiscountAutomaticNode, not DiscountNode or Discount. To route all records to the same table, set gidTypeName to one concrete type and list the others in additionalGidTypeNames.

The following example configures discountNodes correctly:

[
  {
    "apiType": "discountNodes",
    "tableName": "DISCOUNTS",
    "gidTypeName": "DiscountCodeNode",
    "additionalGidTypeNames": ["DiscountAutomaticNode"],
    "graphqlFields": [
      "id",
      "discount { ... on DiscountCodeBasic { title status startsAt endsAt createdAt updatedAt } ... on DiscountAutomaticBasic { title status startsAt endsAt createdAt updatedAt } }"
    ]
  }
]

To verify which GID types appear in a real response before writing the definition, run a small test bulk load or check the Shopify documentation for the concrete types returned by the query root.

Example: Register a custom object type with promoted columns¶

The following override customizes an existing catalog entry to add scalar fields, nested object selections, a metafield alias, and promoted columns. One promoted column extracts a value directly from the aliased metafield.

[
  {
    "apiType": "draftOrders",
    "tableName": "DRAFT_ORDERS",
    "gidTypeName": "DraftOrder",
    "supportsBulk": true,
    "supportsIncremental": true,
    "incrementalField": "updatedAt",
    "ignoredFields": [],
    "sortKeys": ["UPDATED_AT", "ID"],
    "supportsDeletes": false,
    "graphqlFields": [
      "id",
      "createdAt",
      "updatedAt",
      "name",
      "status",
      "email",
      "currencyCode",
      "totalQuantityOfLineItems",
      "customer { id }",
      "totalPriceSet { shopMoney { amount currencyCode } }",
      "billingAddress { address1 city countryCode zip }",
      "draft_po_number: metafield(key: \"custom.draft_po_number\") { key namespace compareDigest createdAt id jsonValue legacyResourceId updatedAt value definition { id description key pinnedPosition } }"
    ],
    "promotedColumns": [
      { "name": "STATUS", "path": "$.status", "type": "string" },
      { "name": "NAME", "path": "$.name", "type": "string" },
      { "name": "CUSTOMER_ID", "path": "$.customer.id", "type": "gid" },
      { "name": "TOTAL_PRICE_AMOUNT", "path": "$.totalPriceSet.shopMoney.amount", "type": "money" },
      { "name": "DRAFT_PO_NUMBER", "path": "$.draft_po_number.value", "type": "string" }
    ],
    "childFields": []
  }
]

Example: Override an object with child fields¶

The following override customizes the orders object to extract line items and fulfillments into separate tables. Line items use a paginated connection (edges); fulfillments are an inline array in the parent response (array).

[
  {
    "apiType": "orders",
    "tableName": "ORDERS",
    "gidTypeName": "Order",
    "graphqlFields": [
      "id",
      "createdAt",
      "updatedAt",
      "name",
      "email",
      "lineItems(first: 250) { edges { cursor node { id title quantity originalUnitPriceSet { shopMoney { amount currencyCode } } } } }",
      "fulfillments { id status createdAt }"
    ],
    "childFields": [
      {
        "fieldName": "lineItems",
        "tableName": "ORDER_LINE_ITEMS",
        "gidTypeName": "LineItem",
        "connectionType": "edges"
      },
      {
        "fieldName": "fulfillments",
        "tableName": "ORDER_FULFILLMENTS",
        "gidTypeName": "Fulfillment",
        "connectionType": "array"
      }
    ]
  }
]