20.21. Unique Indexing

Note

As of Neo4j 2.0, unique constraints have been added. These make Neo4j enforce the uniqueness, guaranteeing that uniqueness is maintained. See the section called “Constraints” for details about this. For most cases, the unique constraints should be used rather than the features described below.

For uniqueness enforcements, there are two modes:

URL Parameter uniqueness=get_or_create: Create a new node/relationship and index it if no existing one can be found. If an existing node/relationship is found, discard the sent data and return the existing node/relationship.
URL Parameter uniqueness=create_or_fail: Create a new node/relationship if no existing one can be found in the index. If an existing node/relationship is found, return a conflict error.

For more information, see Section 18.6, “Creating unique nodes”.

Get or create unique node (create)

The node is created if it doesn’t exist in the unique index already.

Example request

POST http://localhost:7474/db/data/index/node/index_1465360151827_1?uniqueness=get_or_create
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Tobias",
  "properties" : {
    "name" : "Tobias",
    "sequence" : 1
  }
}

Example response

201: Created
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/node/index_1465360151827_1/name/Tobias/21

{
  "extensions" : { },
  "metadata" : {
    "id" : 21,
    "labels" : [ ]
  },
  "paged_traverse" : "http://localhost:7474/db/data/node/21/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/21/relationships/out",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/21/relationships/out/{-list|&|types}",
  "create_relationship" : "http://localhost:7474/db/data/node/21/relationships",
  "labels" : "http://localhost:7474/db/data/node/21/labels",
  "traverse" : "http://localhost:7474/db/data/node/21/traverse/{returnType}",
  "all_relationships" : "http://localhost:7474/db/data/node/21/relationships/all",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/21/relationships/all/{-list|&|types}",
  "property" : "http://localhost:7474/db/data/node/21/properties/{key}",
  "self" : "http://localhost:7474/db/data/node/21",
  "incoming_relationships" : "http://localhost:7474/db/data/node/21/relationships/in",
  "properties" : "http://localhost:7474/db/data/node/21/properties",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/21/relationships/in/{-list|&|types}",
  "data" : {
    "sequence" : 1,
    "name" : "Tobias"
  },
  "indexed" : "http://localhost:7474/db/data/index/node/index_1465360151827_1/name/Tobias/21"
}

Get or create unique node (existing)

Here, a node is not created but the existing unique node returned, since another node is indexed with the same data already. The node data returned is then that of the already existing node.

Example request

POST http://localhost:7474/db/data/index/node/index_1465360150770_1?uniqueness=get_or_create
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Peter",
  "properties" : {
    "name" : "Peter",
    "sequence" : 2
  }
}

Example response

200: OK
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/node/index_1465360150770_1/name/Peter/11

{
  "extensions" : { },
  "metadata" : {
    "id" : 11,
    "labels" : [ ]
  },
  "paged_traverse" : "http://localhost:7474/db/data/node/11/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/11/relationships/out",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/11/relationships/out/{-list|&|types}",
  "create_relationship" : "http://localhost:7474/db/data/node/11/relationships",
  "labels" : "http://localhost:7474/db/data/node/11/labels",
  "traverse" : "http://localhost:7474/db/data/node/11/traverse/{returnType}",
  "all_relationships" : "http://localhost:7474/db/data/node/11/relationships/all",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/11/relationships/all/{-list|&|types}",
  "property" : "http://localhost:7474/db/data/node/11/properties/{key}",
  "self" : "http://localhost:7474/db/data/node/11",
  "incoming_relationships" : "http://localhost:7474/db/data/node/11/relationships/in",
  "properties" : "http://localhost:7474/db/data/node/11/properties",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/11/relationships/in/{-list|&|types}",
  "data" : {
    "sequence" : 1,
    "name" : "Peter"
  },
  "indexed" : "http://localhost:7474/db/data/index/node/index_1465360150770_1/name/Peter/11"
}

Create a unique node or return fail (create)

Here, in case of an already existing node, an error should be returned. In this example, no existing indexed node is found and a new node is created.

Example request

POST http://localhost:7474/db/data/index/node/index_1465360151744_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Tobias",
  "properties" : {
    "name" : "Tobias",
    "sequence" : 1
  }
}

Example response

201: Created
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/node/index_1465360151744_1/name/Tobias/20

{
  "extensions" : { },
  "metadata" : {
    "id" : 20,
    "labels" : [ ]
  },
  "paged_traverse" : "http://localhost:7474/db/data/node/20/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/20/relationships/out",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/20/relationships/out/{-list|&|types}",
  "create_relationship" : "http://localhost:7474/db/data/node/20/relationships",
  "labels" : "http://localhost:7474/db/data/node/20/labels",
  "traverse" : "http://localhost:7474/db/data/node/20/traverse/{returnType}",
  "all_relationships" : "http://localhost:7474/db/data/node/20/relationships/all",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/20/relationships/all/{-list|&|types}",
  "property" : "http://localhost:7474/db/data/node/20/properties/{key}",
  "self" : "http://localhost:7474/db/data/node/20",
  "incoming_relationships" : "http://localhost:7474/db/data/node/20/relationships/in",
  "properties" : "http://localhost:7474/db/data/node/20/properties",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/20/relationships/in/{-list|&|types}",
  "data" : {
    "sequence" : 1,
    "name" : "Tobias"
  },
  "indexed" : "http://localhost:7474/db/data/index/node/index_1465360151744_1/name/Tobias/20"
}

Create a unique node or return fail (fail)

Here, in case of an already existing node, an error should be returned. In this example, an existing node indexed with the same data is found and an error is returned.

Example request

POST http://localhost:7474/db/data/index/node/index_1465360150097_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Peter",
  "properties" : {
    "name" : "Peter",
    "sequence" : 2
  }
}

Example response

409: Conflict
Content-Type: application/json; charset=UTF-8

{
  "extensions" : { },
  "metadata" : {
    "id" : 5,
    "labels" : [ ]
  },
  "paged_traverse" : "http://localhost:7474/db/data/node/5/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/5/relationships/out",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/5/relationships/out/{-list|&|types}",
  "create_relationship" : "http://localhost:7474/db/data/node/5/relationships",
  "labels" : "http://localhost:7474/db/data/node/5/labels",
  "traverse" : "http://localhost:7474/db/data/node/5/traverse/{returnType}",
  "all_relationships" : "http://localhost:7474/db/data/node/5/relationships/all",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/5/relationships/all/{-list|&|types}",
  "property" : "http://localhost:7474/db/data/node/5/properties/{key}",
  "self" : "http://localhost:7474/db/data/node/5",
  "incoming_relationships" : "http://localhost:7474/db/data/node/5/relationships/in",
  "properties" : "http://localhost:7474/db/data/node/5/properties",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/5/relationships/in/{-list|&|types}",
  "data" : {
    "sequence" : 1,
    "name" : "Peter"
  },
  "indexed" : "http://localhost:7474/db/data/index/node/index_1465360150097_1/name/Peter/5"
}

Add an existing node to unique index (not indexed)

Associates a node with the given key/value pair in the given unique index.

In this example, we are using create_or_fail uniqueness.

Example request

POST http://localhost:7474/db/data/index/node/index_1465360151477_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "value" : "some value",
  "uri" : "http://localhost:7474/db/data/node/16",
  "key" : "some-key"
}

Example response

201: Created
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/node/index_1465360151477_1/some-key/some%20value/16

{
  "extensions" : { },
  "metadata" : {
    "id" : 16,
    "labels" : [ ]
  },
  "paged_traverse" : "http://localhost:7474/db/data/node/16/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/16/relationships/out",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/16/relationships/out/{-list|&|types}",
  "create_relationship" : "http://localhost:7474/db/data/node/16/relationships",
  "labels" : "http://localhost:7474/db/data/node/16/labels",
  "traverse" : "http://localhost:7474/db/data/node/16/traverse/{returnType}",
  "all_relationships" : "http://localhost:7474/db/data/node/16/relationships/all",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/16/relationships/all/{-list|&|types}",
  "property" : "http://localhost:7474/db/data/node/16/properties/{key}",
  "self" : "http://localhost:7474/db/data/node/16",
  "incoming_relationships" : "http://localhost:7474/db/data/node/16/relationships/in",
  "properties" : "http://localhost:7474/db/data/node/16/properties",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/16/relationships/in/{-list|&|types}",
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/node/index_1465360151477_1/some-key/some%20value/16"
}

Add an existing node to unique index (already indexed)

In this case, the node already exists in the index, and thus we get a HTTP 409 status response, as we have set the uniqueness to create_or_fail.

Example request

POST http://localhost:7474/db/data/index/node/index_1465360151665_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "value" : "some value",
  "uri" : "http://localhost:7474/db/data/node/19",
  "key" : "some-key"
}

Example response

409: Conflict
Content-Type: application/json; charset=UTF-8

{
  "extensions" : { },
  "metadata" : {
    "id" : 18,
    "labels" : [ ]
  },
  "paged_traverse" : "http://localhost:7474/db/data/node/18/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/18/relationships/out",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/18/relationships/out/{-list|&|types}",
  "create_relationship" : "http://localhost:7474/db/data/node/18/relationships",
  "labels" : "http://localhost:7474/db/data/node/18/labels",
  "traverse" : "http://localhost:7474/db/data/node/18/traverse/{returnType}",
  "all_relationships" : "http://localhost:7474/db/data/node/18/relationships/all",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/18/relationships/all/{-list|&|types}",
  "property" : "http://localhost:7474/db/data/node/18/properties/{key}",
  "self" : "http://localhost:7474/db/data/node/18",
  "incoming_relationships" : "http://localhost:7474/db/data/node/18/relationships/in",
  "properties" : "http://localhost:7474/db/data/node/18/properties",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/18/relationships/in/{-list|&|types}",
  "data" : {
    "some-key" : "some value"
  },
  "indexed" : "http://localhost:7474/db/data/index/node/index_1465360151665_1/some-key/some%20value/18"
}

Get or create unique relationship (create)

Create a unique relationship in an index. If a relationship matching the given key and value already exists in the index, it will be returned. If not, a new relationship will be created.

Note

The type and direction of the relationship is not regarded when determining uniqueness.

Example request

POST http://localhost:7474/db/data/index/relationship/index_1465360166593_1/?uniqueness=get_or_create
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Tobias",
  "start" : "http://localhost:7474/db/data/node/16",
  "end" : "http://localhost:7474/db/data/node/17",
  "type" : "knowledge"
}

Example response

201: Created
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/relationship/index_1465360166593_1/name/Tobias/7

{
  "extensions" : { },
  "metadata" : {
    "id" : 7,
    "type" : "knowledge"
  },
  "start" : "http://localhost:7474/db/data/node/16",
  "property" : "http://localhost:7474/db/data/relationship/7/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/7",
  "end" : "http://localhost:7474/db/data/node/17",
  "type" : "knowledge",
  "properties" : "http://localhost:7474/db/data/relationship/7/properties",
  "data" : {
    "name" : "Tobias"
  },
  "indexed" : "http://localhost:7474/db/data/index/relationship/index_1465360166593_1/name/Tobias/7"
}

Get or create unique relationship (existing)

Here, in case of an already existing relationship, the sent data is ignored and the existing relationship returned.

Example request

POST http://localhost:7474/db/data/index/relationship/index_1465360166646_1?uniqueness=get_or_create
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Peter",
  "start" : "http://localhost:7474/db/data/node/20",
  "end" : "http://localhost:7474/db/data/node/21",
  "type" : "KNOWS"
}

Example response

200: OK
Content-Type: application/json; charset=UTF-8

{
  "extensions" : { },
  "metadata" : {
    "id" : 8,
    "type" : "KNOWS"
  },
  "start" : "http://localhost:7474/db/data/node/18",
  "property" : "http://localhost:7474/db/data/relationship/8/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/8",
  "end" : "http://localhost:7474/db/data/node/19",
  "type" : "KNOWS",
  "properties" : "http://localhost:7474/db/data/relationship/8/properties",
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/index_1465360166646_1/name/Peter/8"
}

Create a unique relationship or return fail (create)

Here, in case of an already existing relationship, an error should be returned. In this example, no existing relationship is found and a new relationship is created.

Example request

POST http://localhost:7474/db/data/index/relationship/index_1465360166783_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Tobias",
  "start" : "http://localhost:7474/db/data/node/28",
  "end" : "http://localhost:7474/db/data/node/29",
  "type" : "KNOWS"
}

Example response

201: Created
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/relationship/index_1465360166783_1/name/Tobias/11

{
  "extensions" : { },
  "metadata" : {
    "id" : 11,
    "type" : "KNOWS"
  },
  "start" : "http://localhost:7474/db/data/node/28",
  "property" : "http://localhost:7474/db/data/relationship/11/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/11",
  "end" : "http://localhost:7474/db/data/node/29",
  "type" : "KNOWS",
  "properties" : "http://localhost:7474/db/data/relationship/11/properties",
  "data" : {
    "name" : "Tobias"
  },
  "indexed" : "http://localhost:7474/db/data/index/relationship/index_1465360166783_1/name/Tobias/11"
}

Create a unique relationship or return fail (fail)

Here, in case of an already existing relationship, an error should be returned. In this example, an existing relationship is found and an error is returned.

Example request

POST http://localhost:7474/db/data/index/relationship/index_1465360166451_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Peter",
  "start" : "http://localhost:7474/db/data/node/8",
  "end" : "http://localhost:7474/db/data/node/9",
  "type" : "KNOWS"
}

Example response

409: Conflict
Content-Type: application/json; charset=UTF-8

{
  "extensions" : { },
  "metadata" : {
    "id" : 3,
    "type" : "KNOWS"
  },
  "start" : "http://localhost:7474/db/data/node/6",
  "property" : "http://localhost:7474/db/data/relationship/3/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/3",
  "end" : "http://localhost:7474/db/data/node/7",
  "type" : "KNOWS",
  "properties" : "http://localhost:7474/db/data/relationship/3/properties",
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/index_1465360166451_1/name/Peter/3"
}

Add an existing relationship to a unique index (not indexed)

If a relationship matching the given key and value already exists in the index, it will be returned. If not, an HTTP 409 (conflict) status will be returned in this case, as we are using create_or_fail.

It’s possible to use get_or_create uniqueness as well.

Note

The type and direction of the relationship is not regarded when determining uniqueness.

Example request

POST http://localhost:7474/db/data/index/relationship/index_1465360166381_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Peter",
  "uri" : "http://localhost:7474/db/data/relationship/2"
}

Example response

201: Created
Content-Type: application/json; charset=UTF-8
Location: http://localhost:7474/db/data/index/relationship/index_1465360166381_1/name/Peter/2

{
  "extensions" : { },
  "metadata" : {
    "id" : 2,
    "type" : "KNOWS"
  },
  "start" : "http://localhost:7474/db/data/node/4",
  "property" : "http://localhost:7474/db/data/relationship/2/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/2",
  "end" : "http://localhost:7474/db/data/node/5",
  "type" : "KNOWS",
  "properties" : "http://localhost:7474/db/data/relationship/2/properties",
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/index_1465360166381_1/name/Peter/2"
}

Add an existing relationship to a unique index (already indexed)

Example request

POST http://localhost:7474/db/data/index/relationship/index_1465360166490_1?uniqueness=create_or_fail
Accept: application/json; charset=UTF-8
Content-Type: application/json

{
  "key" : "name",
  "value" : "Peter",
  "uri" : "http://localhost:7474/db/data/relationship/5"
}

Example response

409: Conflict
Content-Type: application/json; charset=UTF-8

{
  "extensions" : { },
  "metadata" : {
    "id" : 4,
    "type" : "KNOWS"
  },
  "start" : "http://localhost:7474/db/data/node/10",
  "property" : "http://localhost:7474/db/data/relationship/4/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/4",
  "end" : "http://localhost:7474/db/data/node/11",
  "type" : "KNOWS",
  "properties" : "http://localhost:7474/db/data/relationship/4/properties",
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/index_1465360166490_1/name/Peter/4"
}

The Neo4j Manual v3.1.0-SNAPSHOT20.21. Unique Indexing