21.21. Unique Indexing

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

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

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

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

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/favorites?uniqueness=create_or_fail
  • Accept: application/json; charset=UTF-8
  • Content-Type: application/json
{
  "value" : "some value",
  "uri" : "http://localhost:7474/db/data/node/275",
  "key" : "some-key"
}

Example response

  • 201: Created
  • Content-Type: application/json; charset=UTF-8
  • Location: http://localhost:7474/db/data/index/node/favorites/some-key/some%20value/275
{
  "extensions" : { },
  "labels" : "http://localhost:7474/db/data/node/275/labels",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/275/relationships/out",
  "traverse" : "http://localhost:7474/db/data/node/275/traverse/{returnType}",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/275/relationships/all/{-list|&|types}",
  "self" : "http://localhost:7474/db/data/node/275",
  "property" : "http://localhost:7474/db/data/node/275/properties/{key}",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/275/relationships/out/{-list|&|types}",
  "properties" : "http://localhost:7474/db/data/node/275/properties",
  "incoming_relationships" : "http://localhost:7474/db/data/node/275/relationships/in",
  "create_relationship" : "http://localhost:7474/db/data/node/275/relationships",
  "paged_traverse" : "http://localhost:7474/db/data/node/275/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "all_relationships" : "http://localhost:7474/db/data/node/275/relationships/all",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/275/relationships/in/{-list|&|types}",
  "metadata" : {
    "id" : 275,
    "labels" : [ ]
  },
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/node/favorites/some-key/some%20value/275"
}

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/favorites?uniqueness=create_or_fail
  • Accept: application/json; charset=UTF-8
  • Content-Type: application/json
{
  "value" : "some value",
  "uri" : "http://localhost:7474/db/data/node/278",
  "key" : "some-key"
}

Example response

  • 409: Conflict
  • Content-Type: application/json; charset=UTF-8
{
  "extensions" : { },
  "labels" : "http://localhost:7474/db/data/node/277/labels",
  "outgoing_relationships" : "http://localhost:7474/db/data/node/277/relationships/out",
  "traverse" : "http://localhost:7474/db/data/node/277/traverse/{returnType}",
  "all_typed_relationships" : "http://localhost:7474/db/data/node/277/relationships/all/{-list|&|types}",
  "self" : "http://localhost:7474/db/data/node/277",
  "property" : "http://localhost:7474/db/data/node/277/properties/{key}",
  "outgoing_typed_relationships" : "http://localhost:7474/db/data/node/277/relationships/out/{-list|&|types}",
  "properties" : "http://localhost:7474/db/data/node/277/properties",
  "incoming_relationships" : "http://localhost:7474/db/data/node/277/relationships/in",
  "create_relationship" : "http://localhost:7474/db/data/node/277/relationships",
  "paged_traverse" : "http://localhost:7474/db/data/node/277/paged/traverse/{returnType}{?pageSize,leaseTime}",
  "all_relationships" : "http://localhost:7474/db/data/node/277/relationships/all",
  "incoming_typed_relationships" : "http://localhost:7474/db/data/node/277/relationships/in/{-list|&|types}",
  "metadata" : {
    "id" : 277,
    "labels" : [ ]
  },
  "data" : {
    "some-key" : "some value"
  },
  "indexed" : "http://localhost:7474/db/data/index/node/favorites/some-key/some%20value/277"
}

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]Note

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

Example request

  • POST http://localhost:7474/db/data/index/relationship/MyIndex/?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/31",
  "end" : "http://localhost:7474/db/data/node/32",
  "type" : "knowledge"
}

Example response

  • 201: Created
  • Content-Type: application/json; charset=UTF-8
  • Location: http://localhost:7474/db/data/index/relationship/MyIndex/name/Tobias/8
{
  "extensions" : { },
  "start" : "http://localhost:7474/db/data/node/31",
  "property" : "http://localhost:7474/db/data/relationship/8/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/8",
  "properties" : "http://localhost:7474/db/data/relationship/8/properties",
  "type" : "knowledge",
  "end" : "http://localhost:7474/db/data/node/32",
  "metadata" : {
    "id" : 8,
    "type" : "knowledge"
  },
  "data" : {
    "name" : "Tobias"
  },
  "indexed" : "http://localhost:7474/db/data/index/relationship/MyIndex/name/Tobias/8"
}

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/rels?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/35",
  "end" : "http://localhost:7474/db/data/node/36",
  "type" : "KNOWS"
}

Example response

  • 200: OK
  • Content-Type: application/json; charset=UTF-8
{
  "extensions" : { },
  "start" : "http://localhost:7474/db/data/node/33",
  "property" : "http://localhost:7474/db/data/relationship/9/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/9",
  "properties" : "http://localhost:7474/db/data/relationship/9/properties",
  "type" : "KNOWS",
  "end" : "http://localhost:7474/db/data/node/34",
  "metadata" : {
    "id" : 9,
    "type" : "KNOWS"
  },
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/rels/name/Peter/9"
}

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/rels?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/43",
  "end" : "http://localhost:7474/db/data/node/44",
  "type" : "KNOWS"
}

Example response

  • 201: Created
  • Content-Type: application/json; charset=UTF-8
  • Location: http://localhost:7474/db/data/index/relationship/rels/name/Tobias/12
{
  "extensions" : { },
  "start" : "http://localhost:7474/db/data/node/43",
  "property" : "http://localhost:7474/db/data/relationship/12/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/12",
  "properties" : "http://localhost:7474/db/data/relationship/12/properties",
  "type" : "KNOWS",
  "end" : "http://localhost:7474/db/data/node/44",
  "metadata" : {
    "id" : 12,
    "type" : "KNOWS"
  },
  "data" : {
    "name" : "Tobias"
  },
  "indexed" : "http://localhost:7474/db/data/index/relationship/rels/name/Tobias/12"
}

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/rels?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/23",
  "end" : "http://localhost:7474/db/data/node/24",
  "type" : "KNOWS"
}

Example response

  • 409: Conflict
  • Content-Type: application/json; charset=UTF-8
{
  "extensions" : { },
  "start" : "http://localhost:7474/db/data/node/21",
  "property" : "http://localhost:7474/db/data/relationship/4/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/4",
  "properties" : "http://localhost:7474/db/data/relationship/4/properties",
  "type" : "KNOWS",
  "end" : "http://localhost:7474/db/data/node/22",
  "metadata" : {
    "id" : 4,
    "type" : "KNOWS"
  },
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/rels/name/Peter/4"
}

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]Note

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

Example request

  • POST http://localhost:7474/db/data/index/relationship/rels?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/3"
}

Example response

  • 201: Created
  • Content-Type: application/json; charset=UTF-8
  • Location: http://localhost:7474/db/data/index/relationship/rels/name/Peter/3
{
  "extensions" : { },
  "start" : "http://localhost:7474/db/data/node/19",
  "property" : "http://localhost:7474/db/data/relationship/3/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/3",
  "properties" : "http://localhost:7474/db/data/relationship/3/properties",
  "type" : "KNOWS",
  "end" : "http://localhost:7474/db/data/node/20",
  "metadata" : {
    "id" : 3,
    "type" : "KNOWS"
  },
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/rels/name/Peter/3"
}

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

Example request

  • POST http://localhost:7474/db/data/index/relationship/rels?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/6"
}

Example response

  • 409: Conflict
  • Content-Type: application/json; charset=UTF-8
{
  "extensions" : { },
  "start" : "http://localhost:7474/db/data/node/25",
  "property" : "http://localhost:7474/db/data/relationship/5/properties/{key}",
  "self" : "http://localhost:7474/db/data/relationship/5",
  "properties" : "http://localhost:7474/db/data/relationship/5/properties",
  "type" : "KNOWS",
  "end" : "http://localhost:7474/db/data/node/26",
  "metadata" : {
    "id" : 5,
    "type" : "KNOWS"
  },
  "data" : { },
  "indexed" : "http://localhost:7474/db/data/index/relationship/rels/name/Peter/5"
}