Manage Dimension Values

“Dimension value” refer to the child objects in a dimension group.

🚧
The value of dimension is assumed to be a slug and only if the query comes back empty will a query be made against the UID. This means for maximum efficiency its better to use the slug as there will be less calls to DynamoDB.

Create Dimension Values

To create a new dimension value, you must know the UID or slug or external_id of the parent dimension.

In the request, the value for dimension_id can be either that UID or slug. Alternately, external_id of the dimension can also be specified in external_id argument.

Example using slug:

mutation createDimensionValue {
  createDimensionValue(dimension_id: "device-type", dimension_value: {title: "iPhone", slug: "iphone", description: "Apple iPhone"}) {
    # Return fields
    uid
    title
    slug
    description
  }
}

Example using UID:

mutation createDimensionValue {
  createDimensionValue(dimension_id: "c91c0416-0370-4107-8f11-553aa9f00f1f", dimension_value: {title: "iPhone", slug: "iphone", description: "Apple iPhone"}) {
    # Return fields
    uid
    title
    slug
    description
  }
}

Example using external_id

mutation createDimensionValue {
  createDimensionValue(external_id: "ext-id-device-type", dimension_value: {title: "iPhone", slug: "iphone", description: "Apple iPhone", external_id: "ext-id-iphone"}) {
    # Return fields
    uid
    title
    slug
    description
  }
}

Response:

{
  "data": {
    "createDimensionValue": {
      "uid": "a631abb2-5bcd-4240-b28a-2ad3b5d082aa",
      "title": "iPhone",
      "slug": "iphone",
      "description": "Apple iPhone"
    }
  }
}

Get Dimension Values

Dimension values are listed in the values object of their parent dimension. You can either retrieve a full list of all dimensions and their child values with the listDimensions query, or use a dimension slug/uid and the getDimension query to get a specific dimension.

Request for all values in a specific dimension:

query getDimension {
  getDimension(dimension_id: "device-type") {
    uid
    values {
    	objects {
        uid
        title
        slug
      }
    }
  }
}

Response:

{
  "data": {
    "listDimensions": [
      {
        "uid": "3ee81253-336a-43bc-8f19-3de9e4f693cc",
        "title": "Device Type",
        "slug": "device-type",
        "values": {
          "objects": [
            {
              "slug": "pc",
              "description": "Personal Computer",
              "title": "PC"
            },
            {
              "slug": "iphone",
              "description": "Apple iPhone",
              "title": "iPhone"
            },
            {
              "slug": "galaxy",
              "description": "Samsung Galaxy",
              "title": "Galaxy"
            }
          ]
        }
      }
    ]
  }
}

If you know the slug or UID or external_id of the dimension value its possible to include that in the _meta query. Note that the values will still be returned as an array, but with only a single object matching the search criteria.

query getDimension {
  getDimension(dimension_id: "device-type") {
    uid
    values(value_id: "iphone") {
      objects {
        uid
        title
        slug
      }
    }
  }
}

Example using external_id of dimension value

query getDimension {
  getDimension(dimension_id: "device-type") {
    uid
    values(value_external_id: "ext-id-iphone") {
      objects {
        uid
        title
        slug
      }
    }
  }
}

Response:

{
  "data": {
    "getDimensions": [
      {
        "uid": "3ee81253-336a-43bc-8f19-3de9e4f693cc",
        "title": "Device Type",
        "slug": "device-type",
        "values": {
          "objects": [
            {
              "slug": "iphone",
              "description": "Apple iPhone",
              "title": "iPhone"
              
            }
          ]
        }
      }
    ]
  }
}

By listing dimensions, its possible to get all dimensions and their values in a single request:

{
  "data": {
    "listDimensions": [
      {
        "values": {
          "objects": [
            {
              "uid": "3ee81253-336a-43bc-8f19-3de9e4f693cc",
              "title": "PC",
              "slug": "pc"
            },
            {
              "uid": "3ee81253-336a-43bc-8f19-3de9e4f693cc",
              "title": "iPhone",
              "slug": "iphone"
            },
            {
              "uid": "3ee81253-336a-43bc-8f19-3de9e4f693cc",
              "title": "Galaxy",
              "slug": "galaxy"
            }
          ]
        },
        "title": "Device Type",
        "description": "The type of device"
      },
      {
        "values": {
          "objects": [
            {
              "uid": "cdc03468-2ab7-4d33-aa1e-95cbb7d74dd0",
              "title": "MacOS",
              "slug": "macos"
            },
            {
              "uid": "cdc03468-2ab7-4d33-aa1e-95cbb7d74dd0",
              "title": "Windows",
              "slug": "window"
            }
          ]
        },
        "title": "Operating System",
        "description": "The operating system of the machine"
      },
      {
        "values": {
          "objects": [
            {
              "uid": "224b342d-ef55-4378-a043-0fbde8b26a6d",
              "title": "Pro",
              "slug": "pro"
            }
          ]
        },
        "title": "User Context",
        "description": "Additional context for the user"
      }
    ]
  }
}

It is possible to see the availability slots that uses a dimension value.

query getDimension {
  getDimension(dimension_id: "device-type") {
    uid
    values(value_id: "iphone") {
      objects {
        uid
        title
        slug
        availability {
          objects {
            uid
            start
            end
          }
        }
      }
    }
  }
}

Response:

{
  "data": {
    "getDimensions": [
      {
        "uid": "3ee81253-336a-43bc-8f19-3de9e4f693cc",
        "title": "Device Type",
        "slug": "device-type",
        "values": {
          "objects": [
            {
              "slug": "iphone",
              "description": "Apple iPhone",
              "title": "iPhone",
              "availability": {
                "objects": [
                  {
                    "uid": "7e5f319f-a957-4aa9-ab1c-aa157c559513",
                    "start": "2022-10-30T00:00:00Z",
                    "end": "2022-12-31T00:00:00Z"
                  },
                  {
                    "uid": "c4bbc3a1-1bbb-42f8-82ba-f84b3b90f46a",
                    "start": "1970-01-01T00:00:00+00:00",
                    "end": "2038-01-19T03:14:07+00:00"
                  },
                  {
                    "uid": "efe7c438-87b1-474f-a5be-fdc4a7a77b0e",
                    "start": "2022-11-01T00:00:00Z",
                    "end": "2022-12-01T00:00:00Z"
                  }
                ]
              } 
            }
          ]
        }
      }
    ]
  }
}

Update Dimension Values

Updating a dimension value requires:

Either slug or UID or external_id of parent dimension
Either slug or UID or external_id of child value you’re trying to update

Slugs and UIDs can also be mixed for the dimension and value.

Example of making a request with slugs:

mutation updateDimensionValue {
  updateDimensionValue(
    dimension_id: "device-type", 
    value_id: "iphone", 
    dimension_value: {title: "iPhone update"}
  ) {
    # Return fields
    uid
    title
    slug
    description
  }
}

Example of making a request with UIDs:

mutation updateDimensionValue {
  updateDimensionValue(
    dimension_id: "9b828e73-c4d6-4053-b9b5-13eabd5511e6", 
    value_id: "25b0597e-4475-4f15-b117-d0fc6f7a94fa", 
    dimension_value: {title: "iPhone update"}
  ) {
    # Return fields
    uid
    title
    slug
    description
  }
}

Example of making request with external_id

mutation updateDimensionValue {
  updateDimensionValue(
    external_id: "device-type-ext-id", 
    value_external_id: "iphone-ext-id", 
    dimension_value: {title: "iPhone update"}
  ) {
    # Return fields
    uid
    title
    slug
    description
  }
}

Response:

{
  "data": {
    "updateDimensionValue": {
      "uid": "25b0597e-4475-4f15-b117-d0fc6f7a94fa",
      "title": "iPhone update",
      "slug": "iphone",
      "description": "Apple iPhone"
    }
  }
}

Delete Dimension Values

Deleting dimension values is done via the deleteDimensionValue mutation.

Deleting a dimension value requires:

Either slug or UID or external_id of parent dimension
Either slug or UID or external_id of child value you’re trying to update

Slugs and UIDs can also be mixed for the dimension and value.

Example:

mutation deleteDimensionValue {
  deleteDimensionValue(dimension_id: "device-type", value_id: "iphone")
}

No return fields are required when making this request as only a string containing the UID of the deleted value is returned.

{
  "data": {
    "deleteDimensionValue": "0d35f6b8-5fa2-4398-b8a6-7f5050374409"
  }
}

If the matching device type or child value of the device type can be found, a NotFoundexception will be thrown.

🚧
Note that a dimension value cannot be deleted if there are availability slots associated with it.