Running Graph Queries

Running your first graph query

Create your first graph query by creating a POST request to the graph queries resource. You will need to specify the graph query template you want to use, along with the parameters it needs. Please refer to the Graph Query Templates Documentation to see what you need for your specific query.

curl

1 API_KEY=YOUR_API_KEY_HERE
2 curl -X POST -H 'Content-Type: application/json' \
3     -H "Authorization: Bearer $API_KEY" -d'{
4   "data": {
5     "attributes": {
6       "graph-query-template-id": YOUR_TEMPLATE_ID,
7       "parameter-map": {
8         "example-key": "example-value",
9         "...": "...
10       }
11     }
12   }
13 }' https://api.withpersona.com/api/v1/graph-queries

parameter-map should be all the parameter names defined in your graph query template and the value you want to pass in. For example, if you have a parameter account-id in your graph query template, it would look like:

text

{
  "account-id": "act_UqdkF248jR4yH8xxixsMhKnt"
}

After you submit this request to create the graph query, we’ll process it as soon as possible. The response of this request will include a graph query ID which you can use to poll for your query result.

The newly created graph query’s status starts as submitted initially as it is being processed.

json

1 {
2   "data": {
3     "type: "graph-query",
4     "id": "grphq_yourfirstqueryid",
5     "attributes": {
6        "params": {
7          <Your query params>
8        },
9        "created-at": DATE_TIME_STRING,
10        "completed-at": null,
11        "status": "submitted",
12 	   ...
13     }
14   }
15 }

Getting the results of your query

Fetch the results of your graph query using the graph query ID from the graph queries resource.

curl

1 API_KEY=YOUR_API_KEY_HERE
2 curl -X GET -H 'Content-Type: application/json' \
3     -H "Authorization: Bearer $API_KEY" \
4   https://api.withpersona.com/api/v1/graph-queries/GRAPH_QUERY_ID

Once the status is completed, the results are available in the response.

Query response format

json

1 {
2   "data": {
3     "type: "graph-query",
4     "id": "grphq_yourfirstqueryid",
5     "attributes": {
6        "status": "completed",
7        "params": {
8          <Your query params>
9        },
10        "created-at": DATE_TIME_STRING,
11        "updated-at": DATE_TIME_STRING,
12        "errored-at": DATE_TIME_STRING,
13        "completed-at": DATE_TIME_STRING,
14        "stats": {
15          num-accounts: 5,
16          num-device-fingerprints: 2,
17          ...
18        },
19        "explorer-url": LINK_TO_VISUALIZE_QUERY_IN_PERSONA_DASHBOARD,
20        "node-limit-reached": false,
21   		 "nodes": [
22          {
23            "type": "account",
24            "value": "act_123example"
25          },
26          {
27            "type": "device_fingerprint",
28            "value": "123example"
29          },
30          ...
31        ]
32     }
33   }
34 }

Item in Response	Description
`status`	The status of the graph query. It is initially `submitted` and becomes `completed` once Persona is done processing the data.
`params`	The same parameters you passed in when the graph query was created.
`created-at`	The timestamp of when the graph query was first created.
`updated-at`	The timestamp of when the graph query was last updated.
`errored-at`	The timestamp of when the graph query resulted in an error, if any.
`completed-at`	The timestamp of when the graph query result was done being computed (if it is completed)
`stats`	an `object` detailing the counts of each node type in the query response.
`explorer-url`	For any more advanced investigation, it is easiest to use our powerful suite of tools and visualization in Graph Explorer. This link opens your query result there so you can continue your analysis without having to rerun the query.
`nodes`	An array of node objects comprised of attributes defined below:
`value`	The value of the node that Graph uses to determine matches
`type`	The type of node

If your team is interested in learning more about getting additional data in the API response, please let your Persona Graph contact know.

A note on node limits

Every graph query requires processing huge amounts of data and analyzing all of their relationships. To ensure performant queries, the computation will not continue traversing more nodes once it hits the node limit. It will return the accumulated results it has traversed so far. If node-limit-reached is true, the results will only reflect the portion of the graph it has traversed so far. Please reach out to your Persona Graph contact to inquire about pagination.

Best practices

For optimal query performance, try to keep the range of nodes being queried over small. For example:

In general, a query over a smaller created-at time range would be faster.
In general, a query on a more unique node type, such as government ID number, would compute faster than a query on a node type with lots of matches, such as name.