Query real-time segments

7 min

The GraphQL API allows you to view the results of existing segments. This document focuses on the public GraphQL API. For more information on public/private GraphQL API see forming calls with GraphQL. With this API, you can view both the results of segments that we have created for you as well as segments that you have created yourself via the RealtimeSegments API.

On-site personalization often begins with a query for a customer's segment membership. You must use a customer's anonymous identifier to make this query:

query {
  customer(vuid: "7bfa54185ffe45dda85d739a3133e94f") {
    audiences(subset: ["active_visitors", "dc_customers", "email_engaged", "sms_engaged"]) {
      edges {
        node {
          name
        }
      }
    }
  }
}

📘 Note You need to request the set of audiences to which our handler logic is responsive.

In the response, you receive the subset of segments of which the customer is a member. The API only returns the subset of segments that you specified, even if the customer belongs to other segments:

{
  "data": {
    "customer": {
      "audiences": {
        "edges": [
          {
            "node": {
              "name": "active_visitors"
            }
          },
          {
            "node": {
              "name": "dc_customer"
            }
          },
          {
            "node": {
              "name": "email_engaged"
            }
          }
        ]
      }
    }
  }
}

If you are using the private API, you can also query the events that ODP has processed to make this segment membership determination.

📘 Note This API can only classify a customer using data that has made it through the ODP ingest pipeline. Typically, it takes a few seconds for an event sent to ODP to impact segment membership.

Access the VUID property on the zaius object (which is installed on your site by the zaius tag) to determine the VUID in the above Query. The value retrieved from zaius.VUID contains hyphens, which you must remove before issuing the query.

Data takes time to traverse the ODP data pipeline (typically less than 2 minutes). This delay (known as data latency) can impact your segment query results. For example, if you have a customer (zaius_id = 100) who has just recently made an order and that order is still being processed by the ODP ingest pipeline, then when you make the following request:

query {
  customer(zaius_id: "100") {
    audiences(subset: ["has_order"]) {
      edges {
        node { name }
      }
    }
  }
}

Since the order is still being processed by the ODP ingest pipeline and not yet available for segment membership determination, you receive the following empty audience response:

{
  "data": {
    "customer": {
      "audiences": {
        "edges":[]
      }
    }
  }
}

In this case, you can bypass the short delay that is caused by the ODP ingest pipeline by sending the recent order event directly with the GraphQL query:

📘 Note The recent_events field accepts an array of events in the same format as the Events API, but without the identifiers (which are for the user being queried).

query {
  customer(zaius_id: "100") {
    audiences(subset: ["has_order"],
      recent_events: [
        {
          idempotence_id: "random-idempotence-id",
          vdl_action: "purchase",
          type: "order",
          order: {
            order_total: 1.0,
            order_shipping: 0.0,
            phone: "123-456-789",
            order_subtotal: 1.0,
            name: "Default Name",
            order_discount: 0.0,
            ship_address: "123 Default St, , Default City, DF, 94324, Default",
            bill_address: "123 Default St, , Default City, DF, 94324, Default",
            items: [
              {
                item_quantity: 1,
                item_price: 1.0,
                item_subtotal: 1.0,
                product_id: "1"
              },
              {
                item_quantity: 11,
                item_price: 2.0,
                item_subtotal: 22.0,
                product_id: "101"
              },
              {
                item_quantity: 3,
                item_price: 153.0,
                item_subtotal: 459.0,
                product_id: "102"
              }
            ],
            order_id: "1"
          },
          ts: 1447698595
        }
      ]
    ) {
      edges {
        node { name }
      }
    }
  }
}

The response to the above GraphQL query returns all processed events as well as the events that were sent in the recent_events array:

{
  "data": {
    "customer": {
      "audiences": {
        "edges": [
          {
            "node": {
              "name": "has_order"
            }
          }
        ]
      }
    }
  }
}

The recent_events array supports events and entity update events, so you can also put customer update events into the array:

query {
  customer(zaius_id: "100") {
    audiences(subset: ["has_order"],
      recent_events: [
        {
          type: "customer_dimension",
          email: "[email protected]"
        }
      ]
    ) {
      edges {
        node { name }
      }
    }
  }
}

📘 Required fields The following two fields are required for all events (both dimension updates and events):

type

idempotence_id

To avoid duplicate data being observed by your real-time segment definition, you must provide an idempotence_id with the events you send to the Events API and use the same idempotence_id in your recent_events query.