Advanced Queries: Cypher

To send Cypher statements directly to Neo4j, you can use the Cypher Query Resource. The results are wrapped in the typical JSON object representation serialized by Structr’s JSON/REST backend.

The use of Cypher via REST bypasses Structr's security system and the use of it in your application poses a severe security risk. Requests to the Cypher query resource access to the database directly on a level below Structr's security and caching layer, so Structr has no control over modifications or read operations that happen using Cypher.

For that reason, Structr limits access to the Cypher query resource to the superuser and administrative users only (users that have the isAdmin flag set).

You can access the Cypher query resource by sending an HTTP POST request to the /.../cypher resource with the desired query in the request body. The following examples illustrate the usage of the resource:

$ curl -i -HX-User:admin -HX-Password:admin -XPOST http://localhost:8082/structr/rest/cypher -d '{ "query": "MATCH (u:User) RETURN u LIMIT 1" }'

This should return the first user node that was created upon first startup of the Structr instance.

HTTP/1.1 200 OK
Date: Fri, 24 Feb 2017 09:57:46 GMT
Content-Type: application/json; charset=utf-8
Set-Cookie: JSESSIONID=g6o0gh0f1u6vnincler690hs;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Vary: Accept-Encoding, User-Agent
Content-Length: 188
Server: Jetty(9.2.9.v20150224)

{
  "result_count": 1,
  "result": {
    "id": "70fd9f831cad4506a1076f956ffa2a0b",
    "type": "User",
    "name": "admin",
    "isUser": true
  },
  "serialization_time": "0.000149306"
}

This query returns only the relationship between the user and a file.

$ curl -i -HX-User:admin -HX-Password:admin -XPOST http://localhost:8082/structr/rest/cypher -d '{ "query": "MATCH (u:User)-[r:OWNS]->(m) RETURN r LIMIT 1" }'


HTTP/1.1 200 OK
Date: Fri, 24 Feb 2017 10:00:58 GMT
Content-Type: application/json; charset=utf-8
Set-Cookie: JSESSIONID=1156ekwea4t1i1es66a5o4iclh;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Vary: Accept-Encoding, User-Agent
Content-Length: 287
Server: Jetty(9.2.9.v20150224)

{
  "result_count": 1,
  "result": {
    "id": "6dc2800e4d1943b4b9713aa07ca4fed3",
    "type": "PrincipalOwnsNode",
    "relType": "OWNS",
    "sourceId": "70fd9f831cad4506a1076f956ffa2a0b",
    "targetId": "c39d33f0714f4e4b9cf6adf3b62c9487"
  },
  "serialization_time": "0.000116034"
}

You can also access individual properties separately:

$ curl -i -HX-User:admin -HX-Password:admin -XPOST http://localhost:8082/structr/rest/cypher -d '{ "query": "MATCH (u:User)-[r:OWNS]->(f) RETURN u.name LIMIT 1" }'

HTTP/1.1 200 OK
Date: Fri, 24 Feb 2017 11:50:05 GMT
Content-Type: application/json; charset=utf-8
Set-Cookie: JSESSIONID=9zglt11egjt7nodnvlcf8790;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Vary: Accept-Encoding, User-Agent
Content-Length: 104
Server: Jetty(9.2.9.v20150224)

{
  "result_count": 1,
  "result": {
    "u.name": "admin"
  },
  "serialization_time": "0.000024772"
}

Or let Structr return a mixed JSON document with objects and single values:

curl -i -HX-User:admin -HX-Password:admin -XPOST http://localhost:8082/structr/rest/cypher -d '{ "query": "MATCH (u:User)-[r:OWNS]->(f) RETURN f, f.size, u LIMIT 1" }'


HTTP/1.1 200 OK
Date: Fri, 24 Feb 2017 11:45:08 GMT
Content-Type: application/json; charset=utf-8
Set-Cookie: JSESSIONID=1tqkxehac75c2z3683mm2d8f;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Vary: Accept-Encoding, User-Agent
Content-Length: 3051
Server: Jetty(9.2.9.v20150224)

{
  "result_count": 3,
  "result": [
    {
      "id": "30f06af877e24fc899246fe88771b82e",
      "size": 5430,
      "url": null,
      "isFile": true,
      "visibleToPublicUsers": false,
      "visibleToAuthenticatedUsers": false,
      "includeInFrontendExport": false,
      "isFavoritable": true,
      "contentType": "image/vnd.microsoft.icon",
      "type": "Image",
      "name": "favicon.ico",
      "width": null,
      "height": null,
      "orientation": null,
      "tnSmall": {
        "id": "30f06af877e24fc899246fe88771b82e",
        "size": 5430,
        "url": null,
        "isFile": true,
        "visibleToPublicUsers": false,
        "visibleToAuthenticatedUsers": false,
        "includeInFrontendExport": false,
        "isFavoritable": true,
        "contentType": "image/vnd.microsoft.icon",
        "type": "Image",
        "name": "favicon.ico",
        "width": null,
        "height": null,
        "orientation": null,
        "tnSmall": {
          "id": "30f06af877e24fc899246fe88771b82e"
        },
        "tnMid": {
          "id": "30f06af877e24fc899246fe88771b82e"
        },
        "isThumbnail": false,
        "owner": {
          "id": "f02e59a47dc9492da3e6cb7fb6b3ac25"
        },
        "parent": {
          "id": "3430de55d66a4a41ad3b170966a8e447"
        },
        "path": "/img/favicon.ico",
        "isImage": true
      },
      "tnMid": {
        "id": "30f06af877e24fc899246fe88771b82e",
        "size": 5430,
        "url": null,
        "isFile": true,
        "visibleToPublicUsers": false,
        "visibleToAuthenticatedUsers": false,
        "includeInFrontendExport": false,
        "isFavoritable": true,
        "contentType": "image/vnd.microsoft.icon",
        "type": "Image",
        "name": "favicon.ico",
        "width": null,
        "height": null,
        "orientation": null,
        "tnSmall": {
          "id": "30f06af877e24fc899246fe88771b82e"
        },
        "tnMid": {
          "id": "30f06af877e24fc899246fe88771b82e"
        },
        "isThumbnail": false,
        "owner": {
          "id": "f02e59a47dc9492da3e6cb7fb6b3ac25"
        },
        "parent": {
          "id": "3430de55d66a4a41ad3b170966a8e447"
        },
        "path": "/img/favicon.ico",
        "isImage": true
      },
      "isThumbnail": false,
      "owner": {
        "id": "f02e59a47dc9492da3e6cb7fb6b3ac25",
        "type": "User",
        "name": "admin",
        "isUser": true
      },
      "parent": {
        "id": "3430de55d66a4a41ad3b170966a8e447",
        "path": "/img",
        "type": "Folder",
        "name": "img",
        "owner": {
          "id": "f02e59a47dc9492da3e6cb7fb6b3ac25"
        },
        "isFolder": true,
        "folders": null,
        "files": null,
        "parentId": null
      },
      "path": "/img/favicon.ico",
      "isImage": true
    },
    {
      "f.size": 5430
    },
    {
      "id": "f02e59a47dc9492da3e6cb7fb6b3ac25",
      "type": "User",
      "name": "admin",
      "isUser": true
    }
  ],
  "serialization_time": "0.004610089"
}

You can also use parameters in your query (the complete set of REST query parameters is passed into the cypher query):

$ curl -i -HX-User:admin -HX-Password:admin -XPOST http://localhost:8082/structr/rest/cypher -d '{ "query": "MATCH (u:User {name: {searchForUsername}}) RETURN u.name", "searchForUsername": "admin" }'

HTTP/1.1 200 OK
Date: Fri, 24 Feb 2017 11:50:05 GMT
Content-Type: application/json; charset=utf-8
Set-Cookie: JSESSIONID=9zglt11egjt7nodnvlcf8790;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Vary: Accept-Encoding, User-Agent
Content-Length: 104
Server: Jetty(9.2.9.v20150224)

{
  "result_count": 1,
  "result": {
    "u.name": "admin"
  },
  "serialization_time": "0.000024772"
}