Shopify용 Openflow Connector의 객체 정의 오버라이드

Shopify용 Openflow Connector의 객체 정의 오버라이드

이 페이지에서는 Object Definitions Override 파라미터를 자세히 설명해요. 전체 스키마, 승격 열(promoted column)과 하위 필드 정의, 그리고 완전한 예시를 포함합니다. Shopify 객체를 사용자 정의로 확장하거나 바꿔치기하려는 경우 유용합니다.

출처: Snowflake 문서

본문

Note

이 커넥터는 Snowflake Connector Terms에 의해 규율됩니다.

이 토픽은 Object Definitions Override 파라미터를 상세히 설명합니다. 전체 스키마, 승격 열과 하위 필드 정의, 그리고 완전한 예시를 포함해요.

Object Definitions Override 파라미터는 객체 정의의 JSON 배열을 받습니다. 각 정의는 새 객체 유형을 추가하거나 기존 카탈로그 항목을 완전히 교체할 수 있습니다.

객체 정의 스키마

Important

Object Definitions Override 값은 유효한 JSON이어야 합니다. JSON이 잘못되면 커넥터가 시작에 실패합니다. 오버라이드를 적용하기 전에 JSON을 검증하세요.

각 객체 정의에서 지원되는 필드는 다음과 같습니다:

승격 열 (Promoted columns)

승격 열은 원시 JSON 페이로드에서 특정 값을 추출해 대상 테이블의 전용 타입 열로 만듭니다. 이렇게 하면 자주 조회하는 필드를 일급 Snowflake 열로 사용할 수 있어 효율적인 필터링·집계가 가능합니다.

각 승격 열은 다음 필드를 가집니다:

하위 필드 (Child fields)

하위 필드 정의는 중첩 연결(예: 주문 라인 아이템)을 별도 Snowflake 테이블로 추출합니다. 각 하위 테이블에는 레코드를 부모로 연결하는 __PARENT_ID 열이 포함됩니다.

각 하위 필드는 다음 필드를 가집니다:

Note

Shopify는 250을 초과하는 pageSize 값을 first cannot exceed 250 오류로 거부합니다. 이 한도는 벌크 로드에는 적용되지 않습니다: Shopify Bulk Operations API는 first: 인자를 무시하고 모든 하위 레코드를 반환합니다. 자세한 내용은 Limitations를 참고하세요.

유니온 타입과 GID 라우팅

쿼리 루트가 유니온 타입을 반환하면 Shopify Bulk API 응답의 레코드는 쿼리 루트 이름이나 GraphQL 유니온 타입 이름이 아니라 구체적인 래퍼 노드 타입에 해당하는 GID 유형을 지닙니다. 커넥터의 PartitionShopifyByObject 프로세서는 GID 유형으로 레코드를 라우팅하므로, GID 유형이 gidTypeName 또는 additionalGidTypeNames에 등록되지 않으면 레코드는 실패로 라우팅됩니다.

예를 들어 discountNodes 쿼리 루트는 Discount 유니온을 반환합니다. 응답의 레코드는 DiscountNode나 Discount가 아니라 DiscountCodeNode와 DiscountAutomaticNode GID 유형을 지닙니다. 모든 레코드를 같은 테이블로 라우팅하려면 gidTypeName을 하나의 구체적 타입으로 설정하고 나머지를 additionalGidTypeNames에 나열하세요.

다음 예시는 discountNodes를 올바르게 구성합니다:

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

Note

유니온 타입 객체에서 promotedColumns를 사용할 때, 파티셔닝 후 JSON 루트는 래퍼 노드입니다(예: { id, discount: { … } }), 내부 유니온 멤버가 아닙니다. 승격 열 path 값에는 래퍼 필드가 포함되어야 합니다(예: $.title이 아니라 $.discount.title).

증분 지원과 함께 할인을 동기화하려면 codeDiscountNodes나 automaticDiscountNodes보다 discountNodes를 사용하세요. 하위 유형별 쿼리 루트는 updated_at을 필터로 받아들이지 않아서 supportsIncremental: false와 refreshStrategy: "FULL_PERIODIC"가 필요합니다.

정의를 작성하기 전에 실제 응답에 어떤 GID 유형이 나타나는지 확인하려면 작은 테스트 벌크 로드를 실행하거나, 쿼리 루트가 반환하는 구체적 타입에 대한 Shopify 문서를 확인하세요.

예시: 승격 열과 함께 사용자 정의 객체 유형 등록

다음 오버라이드는 기존 카탈로그 항목을 사용자 정의해 스칼라 필드, 중첩 객체 선택, 메타필드 별칭, 승격 열을 추가합니다. 하나의 승격 열은 별칭이 붙은 메타필드에서 값을 직접 추출합니다.

[
  {
    "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": []
  }
]

예시: 하위 필드가 있는 객체 오버라이드

다음 오버라이드는 orders 객체를 사용자 정의해 라인 아이템과 주문 처리를 별도 테이블로 추출합니다. 라인 아이템은 페이지네이션 연결(edges)을, 주문 처리는 부모 응답의 인라인 배열(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"
      }
    ]
  }
]

더 알아보기 (Learn more)

• Openflow Connector for Shopify 소개
• Openflow Connector for Shopify 설정