Ingesting instances into a graph

This section describes how to ingest and remove instances in a graph using the /apply and /delete endpoints.

Applying instances

This example apply request attempts to ingest a node with the external ID pump42 into the space equipment, and set the Pump/v1.producer view property to "Acme Inc.".

items:
  - instanceType: node
    space: equipment
    externalId: pump42
    sources:
      - source:
          type: view
          space: equipment
          externalId: Pump
          version: v1
        properties:
          producer: 'Acme Inc.'

You can also ingest properties directly into containers. All instances in a request are applied atomically, and you can apply a mix of nodes and edges. Consequently, all instances in a request are applied, or the entire request fails.

Create, patch, and replace

When you apply instances, you can use three distinct modes depending on the existing state and the request parameters.

• If the instance does not exist at the time of ingestion, it will be created. This means that all required properties must be set.

• If the instance already exists, you have two updating methods: patch and replace. You choose the method by setting the value of the replace flag. The value can be true or false, and the default value is false.

  With patch, only the properties that are provided in the sources section of the request will be updated, leaving all other properties unchanged.

With replace, all properties will be updated, and omitted properties will be set to null. Consequently, all required properties must have a value specified in the request body when you update an instance with replace=true.

Autocreate nodes

When ingesting instances, you can autocreate the targets of direct relation properties and ingest a graph without worrying about the order in which you ingest the instances. Use these properties to control this behavior:

• autoCreateDirectRelations: automatically create all direct relations in the request if a relation is not previously created (default: true.)
• autoCreateStartNodes: when set to true, automatically create any missing start nodes for the edge (default: false.) When the parameter is set to false and the indicated start node is not present, the request will fail with a HTTP status code of 409, indicating a conflict with the current state of the service.
• autoCreateEndNodes: when set to true, automatically create any missing end nodes for the edge (default: false.) When the parameter is set to false and the indicated end node is not present, the request will fail with a HTTP status code of 409, indicating a conflict with the current state of the service.

You need write access to a space to autocreate nodes in it.

Optimistic concurrency control

Every instance has a version number that increments every time the instance is modified. The apply endpoint supports optimistic concurrency control and allows you to specify an expected existing version on the instance. If an actual version is greater than the expected version, the request fails with status code 409.

The following example creates a pump node with the external ID "pump42". We set existingVersion to 0 to make sure the node does not exist, and that you will be creating the node.

If the node equipment.pump42 already exists, the request will fail. If it doesn't exist, the node is created.

items:
  - instanceType: node
    space: equipment
    externalId: pump42
    existingVersion: 0

The next example illustrates a case where you want to update the node equipment.pump42 and set the Pump/v1.producer property to "Acme Inc.", but only if the producer property is currently null, to prevent you from overwriting someone else's changes.

First, read the node and verify that the producer property is null and then apply the update specifying existingVersion=$currentVersion. If the first read request returns version: 1, you can apply the instance:

items:
  - instanceType: node
    space: equipment
    externalId: pump42
    existingVersion: 1
    sources:
      - source:
          type: view
          space: equipment
          externalId: Pump
          version: v1
        properties:
          producer: 'Acme Inc.'

If someone else has set the producer property in the meantime, the request has bumped the version of the node to 2. Since you specified existingVersion: 1, the request would fail with status code 409. You can read the node again, check if the producer property is null, and repeat the process.

You can also not fail the entire request when there are version conflicts, and instead ignore updates to the instances that have version conflicts. You do this by setting skipOnVersionConflict to true in the request.

Deleting instances

attention

If you have stored data across multiple containers using the same space and externalId combination, calling delete will delete all the data pertaining to the node.

To delete nodes and edges from the graph, you send a list of fully qualified external IDs to the /delete endpoint. This example deletes a node and an edge:

items:
  - instanceType: node
    space: equipment
    externalId: pump42
  - instanceType: edge
    space: equipment
    externalId: i-dont-exist

The response from this request contains only the successfully deleted instances. In this case, only the node equipment.pump42, since the equipment.i-dont-exist edge does not exist:

items:
  - instanceType: node
    space: equipment
    externalId: pump42

Soft deletion

To support syncing deletes to secondary stores, instances are always soft deleted at first. The soft-deleted instances will be returned by the /sync endpoint with deletedTime set to a non-null value.

After a grace period (3 days by default), the instances are deleted by the system. Soft deleted instances count towards the total instance limits for you CDF project.

remarque

You can not restore soft deleted instances.

Delete edges before nodes

Deleting a node will delete all edges connected to that node. It is a best practice to delete the edges before the nodes in order to avoid long running cascading deletes. It is critical to delete edges before the nodes when you have nodes with a large number of edges pointing to/from them.