Skip to content
Vendia

Unique Identifiers

When you create an item for an entity in your uni, Vendia generates a unique id for the item. You can use this id to perform CRUD operations on the item.

Unique Identifiers allow you to perform the same CRUD operations using a custom, user defined identifier instead of the Vendia generated id.

When using unique identifiers, Vendia will still generate a unique id per item. Both the Vendia generated id and your Unique Identifiers can be used interchangeably to identify items.

Adding Unique Identifiers

Specific fields in the JSON schema can be marked as unique identifiers using the x-vendia-unique definition.

Once marked, Vendia will generate new queries and mutations in your GraphQL schema for any entity with unique identifiers set. The new queries and mutations will allow you to specify either id or any of the specified unique identifiers when referencing items for CRUD operations.

Here is an example of an x-vendia-unique definition specifying two fields as unique identifiers:

"x-vendia-unique": [
    "name",
    "sku"
],

You can also see a full example in the sample schema section below

Please also see limitations around unique identifiers.

Using Unique Identifiers

Mutations

Add Mutations

When creating an item with an add mutation, any unique identifiers specified in the input will also be added to the system.

For example, the following add_Inventory mutation will create a new item (that will generate a new id) and it will create a new unique identifier for both name and sku, assuming they do not already exist in the datastore.

add_Inventory(
   input: {
       name: "running shoe",
       availableInventory: 945,
       warehouse: "US-W-31-A",
       sku: "SHO-12-RUN-US"
   }
) { transaction { transactionId } }

Put and Upsert Mutations

Put mutations will perform an upsert if no identifiers are specified outside of the input, or a normal put operation if an identifier is used.

Put

Put operations update an item by replacing the entire item with the input specified in the mutation, if an identifier is specified outside of the input.

For example, the following put_Inventory mutation will replace the entire item, specified by the sku identifier passed outside of the input.

put_Inventory(
   sku: "LIM-10-RUN-US"
   input: {
     name: "running shoe",
     availableInventory: 645,
     warehouse: "US-W-31-A",
     sku: "LIM-10-RUN-US"
   }
) { transaction { transactionId } }
Upsert

Upsert operations are performed when an identifier is not passed outside of the input. This will either update the item by replacing the entire item with the input specified in the mutation (if the unique identifier exists) or create a new item with the input (if the unique identifier does not exist).

In this example, the following put_Inventory mutation will perform an upsert and will either create a new item if there is no Inventory product with the sku LIM-10-RUN-US or will replace the existing item.

put_Inventory(
   input: {
     availableInventory: 12,
     warehouse: "EU-W-12-C",
     sku: "LIM-10-RUN-US"
   }
) { transaction { transactionId } }

Update / Remove / Erase Mutations

With unique identifiers specified on the entity, these mutations will allow you to reference specific items by their unique identifier.

For example, you can use the following update_Inventory mutation to update the availableInventory field, by using the unique identifier sku to identify the Inventory

update_Inventory(
   sku: "LIM-10-RUN-US"
   input: {
       availableInventory: 5
   }
) {
   result {
       _id
       name
       color
   }
 }

Queries

Both Get and List Version queries can also use unique identifiers to specify the item.

Example Get query:

query getInventoryQuery {
  get_Inventory(name: "running shoe") {
    sku
    name
    warehouse
    availableInventory
  }
}

Example List Version query:

query listInventoryVersionsQuery {
  list_InventoryVersions(sku: "LIM-10-RUN-US") {
    versions {
      block
      ordinal
    }
  }
}

Unique Identifier Limits

  • Limited to 2 unique identifiers per entity
  • Unique identifiers can only be set on top-level array data types. See our data modeling documentation
  • Unique identifiers are limited to number or string values
  • You cannot make an existing entity field a unique identifier
  • All nodes are required to have read access for unique identifiers
    • This means that when specifying aclInputs, you must include * read access for unique identifiers.
    • As a result, locally erasing unique identifier fields is not supported, but global erasure is supported.
  • Unique identifiers cannot be modified once added to an item
  • To remove a unique identifier, you must remove the entire item

Sample Schema

The following sample schema has two unique identifiers on two different entity types.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://vendia.net/schemas/demos/track-and-trace.json",
  "title": "Track and Trace",
  "description": "Track and trace shipments among a manufacturer, shipper, and retailer",
  "type": "object",
  "properties": {
    "Inventory": {
      "description": "Inventory information",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "Product name",
            "type": "string"
          },
          "sku": {
            "description": "Product SKU",
            "type": "string"
          },
          "warehouse": {
            "description": "Manufacturer warehouse code",
            "type": "string"
          },
          "availableInventory": {
            "description": "Available inventory",
            "type": "integer"
          }
        },
        "x-vendia-unique": ["name", "sku"]
      }
    },
    "Warehouse": {
      "description": "Warehouse information",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "companyName": {
            "description": "Company name",
            "type": "string"
          },
          "code": {
            "description": "Warehouse code",
            "type": "string"
          },
          "street1": {
            "description": "Warehouse Street Address",
            "type": "string"
          },
          "street2": {
            "description": "Warehouse Warehouse Street Address Continued",
            "type": "string"
          },
          "city": {
            "description": "Warehouse City",
            "type": "string"
          },
          "state": {
            "description": "Warehouse State",
            "type": "string"
          },
          "postalCode": {
            "description": "Warehouse Postal Code",
            "type": "string"
          },
          "country": {
            "description": "Warehouse Country Code",
            "type": "string"
          },
          "phone": {
            "description": "Warehouse Phone Number",
            "type": "string"
          },
          "fax": {
            "description": "Warehouse Fax Number",
            "type": "string"
          },
          "created": {
            "description": "When the Warehouse record was created",
            "type": "string",
            "format": "date-time"
          },
          "updated": {
            "description": "When Warehouse record was last updated",
            "type": "string",
            "format": "date-time"
          }
        },
        "x-vendia-unique": ["code", "phone"]
      }
    }
  }
}