Object definition overrides for the Openflow Connector for Shopify¶

Note

This connector is subject to the Snowflake Connector Terms.

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¶

Important

The Object Definitions Override value must be valid JSON. If the JSON is malformed, the connector fails to start. Validate your JSON before applying the override.

The following fields are supported in each object definition:

Field	Description
`apiType`	(Required) The query endpoint name in the Shopify Admin GraphQL API. This must match the root query field exactly (for example, `orders` for the orders query, `products` for the products query). Used as the key for lookup and override matching.
`tableName`	(Required) The Snowflake destination table name.
`gidTypeName`	The Shopify GID resource type (for example, `Order`, `Product`). Used for delete cascade and child record routing.
`additionalGidTypeNames`	Array of additional GID type names that also map to this object. Use when Shopify returns the same resource under more than one GID type name, so that records are routed to the correct table regardless of which GID type appears in the response.
`graphqlFields`	List of GraphQL selection fields. Each entry is a field name, a nested selection (for example, `"totalPriceSet { shopMoney { amount currencyCode } }"`), or an aliased field with arguments (for example, `"tier: metafield(key: \"custom.tier\") { value }"`). Aliases are useful for querying metafields by key.
`requiredQueryArgs`	Map of fixed GraphQL argument key-value pairs appended to every query for this object. Use for endpoints that require non-standard arguments that aren’t covered by the built-in query parameters (for example, `{"type": "SALES_CHANNEL"}`).
`supportsIncremental`	Whether the object supports incremental sync. Default: `true`.
`incrementalField`	The field used for watermark-based incremental queries (for example, `updatedAt`, `createdAt`).
`refreshStrategy`	Controls the sync mode. `INCREMENTAL` (default) uses watermark-based incremental queries. `FULL_PERIODIC` performs a complete re-sync on each run instead. `PARENT_PIGGYBACKED` means this object is extracted from another object’s query response and is not queried independently.
`supportsDeletes`	Whether the connector should track deletion events for this object. Default: `false`.
`promotedColumns`	Array of column definitions that extract values from the JSON payload into dedicated Snowflake columns. See Promoted columns.
`childFields`	Array of child connection definitions that are extracted into separate tables. See Child fields.
`ignoredFields`	List of field names to exclude from queries.
`supportsBulk`	Whether the object supports bulk queries through the Shopify Bulk Operations API. Default: `true`.
`sortKeys`	List of sort key values (from the object’s corresponding `SortKeys` enum) used to order results during bulk and incremental queries. For example, `["UPDATED_AT", "ID"]`.
`sortKeyStyle`	How sort key values are formatted in queries. `ENUM` (default) uses bare enum values (for example, `UPDATED_AT`). `STRING` uses quoted lowercase strings (for example, `"updated_at"`). Use `STRING` for object types that accept string sort keys, such as metaobjects.

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:

Field	Description
`name`	The Snowflake column name (uppercase recommended).
`path`	A JSONPath expression pointing to the value in the raw record (for example, `$.email`, `$.totalPriceSet.shopMoney.amount`).
`type`	The column type: `string`, `integer`, `boolean`, `float`, `money`, `timestamp`, `date`, `id`, `gid`, or `json`.

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:

Field	Description
`fieldName`	The GraphQL connection field name in the parent object (for example, `lineItems`).
`tableName`	The Snowflake table name for the child records.
`gidTypeName`	The Shopify GID type for the child (for example, `LineItem`).
`connectionType`	`edges` (paginated connection) or `array` (inline array). Default: `edges`.
`pageSize`	Number of child records to fetch per page. Default: `250`.
`graphqlFields`	Explicit GraphQL selection set for the child table. If omitted, the connector parses the child’s fields from the matching connection entry in the parent’s `graphqlFields` list.
`promotedColumns`	Array of promoted column definitions for the child table, using the same schema as top-level `promotedColumns`.

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"
      }
    ]
  }
]