Skip to main content

Entity and relationship queries

This query will allow you to run J1QL queries for fetching data. The GraphQL resolver requires that one parameter is provided:

  • query: A J1QL query string that describes what data to return

Optionally, additional parameters can be provided:

  • variables: A JSON map of values to be used as parameters for the query
  • cursor: A token that can be exchanged to fetch the next page of information.
  • includeDeleted: When set to true, recently deleted information will be included in the results.
  • deferredResponse: This option allows for a deferred response to be returned. When a deferred response is returned, a url pointing the state of the query is provided. API consumers should poll the status of the deferred query by requesting the given url until the status property of the returned JSON document has a value of COMPLETED (see example below). Upon completion of the query, the url will provide a link to the query results. The results contain the same type, data, and cursor fields that the non-deferred GraphQL response would contain. Allowed values are DISABLED and FORCE.
  • flags:
    • computedProperties: When set to true, vertices will be tagged with additional information to indicate if there are noteworthy traits that are worth surfacing.
    • rowMetadata: When set to true, table results will return metadata about the requested objects under a _meta property.
    • variableResultSize: When set to true the API will return the largest result size possible. Without this flag, the result size will be limited to 250 rows. This flag is recommended for use in cases where a larger result size is preferable and an indeterminate/variable number of return results is acceptable.
  • scopeFilters: An array of JSON map of filters that define the desired vertex. They have precedence over filters supplied in the query.

When working with additional variables, keep in mind some of the following considerations:

  • variableResultSize can increase the rate of your pagination flow because the API will return the largest number of rows possible per request. The exact number of rows returned will not always be the same, but will be larger than the default -- hence the name, variable result size.

  • When paging through data, it is highly recommended that cursors are leveraged instead of adding limit and skip clauses to queries.

  • Be sure to include cursor in the GraphQL response if you need to paginate through the results. The returned cursor will be null if there are no more pages available.

  • Queries that may take longer than 30 seconds should use the FORCE option for deferredResponse to avoid request timeouts. You should only use the DISABLED option when testing a simple query. It is highly recommended that all automated processes use the the FORCE option when issuing J1QL queries.

Example GraphQL query:

query J1QL($query: String!, $variables: JSON, $cursor: String, $scopeFilters: [JSON!], $flags: QueryV1Flags) {
  queryV1(query: $query, variables: $variables, cursor: $cursor, scopeFilters: $scopeFilters, flags: $flags) {
    type
    data
    cursor
  }
}

Example variables:

{
  "query": "find Person with _type=${type} return Person.name",
  "variables": {
    "type": "employee"
  },
  "cursor": "eyJjYWNoZUtleSI6IjFlNDg3MT...",
  "scopeFilters": [
    {
      "org": "engineering"
    }
  ],
  "flags": {
    "computedProperties": true
  }
}

Example queryV1 resolver result:

{
  "type": "table",
  "data": [{ "Person.name": "Mochi" }],
  "cursor": "eyJjYWNoZUtleSI6IjFlNDg3MT..."
}

Example GraphQL query with deferred responses:

query J1QL(
  $query: String!
  $variables: JSON
  $cursor: String
  $deferredResponse: DeferredResponseOption
) {
  queryV1(
    query: $query
    variables: $variables
    deferredResponse: $deferredResponse
    cursor: $cursor
  ) {
    type
    url
  }
}

Example variables:

{
  "query": "find Person with _type=${type}",
  "deferredResponse": "FORCE",
  "variables": {
    "type": "employee"
  },
  "cursor": "eyJjYWNoZUtleSI6IjFlNDg3MT..."
}

Example queryV1 resolver result when using a deferred response:

{
  "type": "deferred",
  "url": "https://example.com/state.json"
}

Example state responses:

{
  "status": "IN_PROGRESS",
  "correlationId": "912788f1-e0c7-43bd-b853-455c0031be8a"
}
{
  "status": "COMPLETED",
  "url": "https://example.com/results.json",
  "correlationId": "912788f1-e0c7-43bd-b853-455c0031be8a"
}

Retrieving a Single Vertex by ID​

This query fetches a vertex and its properties by its ID. The query requires one of two parameters:

  • id: The ID as a string
  • filters: A set of filters that define the desired vertex.

The example below contains all of the currently available filters.

note

Only one of the variables (id or filters) is required. Specifying both is allowed but unnecessary unless you want to assert that a vertex with the specified id exists and has specific entity properties.

query VertexQuery($id: String!, $filters: VertexFilters) {
  vertex(id: $id, filters: $filters) {
    id
    entity {
      _id
      _key
      _type
      _accountId
      _integrationName
      _integrationDefinitionId
      _integrationInstanceId
      _version
      _createdOn
      _beginOn
      _endOn
      _deleted
      displayName
    }
    properties
  }
}

Variables:

{
  "id": "<a vertex id>",
  "filters": {
    "_id": "<an entity id>",
    "_key": "<an entity key>",
    "_type": ["<a entity type>"],
    "_class": ["<a entity class>"]
  }
}

Fetching Neighbors of a Vertex​

The Vertex type allows you to retrieve vertex and edge neighbors up to a certain depth using the neighbors field. The return type of the neighbors resolver is the same as that of a graph query. This query requires two parameters:

  • id: The ID of the vertex as a string
  • depth: An integer specifying how many "levels" deep the query will go to look for neighbors.
query VertexQuery($id: String!, $depth: Int) {
  vertex(id: $id) {
    id
    entity {
      displayName
    }
    neighbors(depth: $depth) {
      vertices {
        id
        entity {
          displayName
        }
      }
      edges {
        id
        relationship {
          displayName
        }
      }
    }
  }
}

Variables:

The depth that is supplied must be a value between 1 and 5 (inclusive).

{
  "id": "<a vertex id>",
  "depth": 5
}

Retrieving an Edge by ID​

This query allows you to fetch an edge, its properties, and the relationship it describes by its ID or label and filters. The query requires one or two of three parameters:

  • id: The ID as a string.
  • label: The label displayed on the edge.
  • filters: A set of filters that define the desired vertex.

Only one of the variables (id, label, or filters) is required. Specifying label and filters with id is allowed but somewhat redundant unless you want to assert that a vertex with the specified id exists and has the specific label and properties.

The example below contains all of the currently available filters.

query VertexQuery($id: String!) {
  edge(id: $id, label: $id, filters: $id) {
    id
    relationship {
      _id
      _key
      _type
      _accountId
      _integrationName
      _integrationDefinitionId
      _integrationInstanceId
      _version
      _createdOn
      _beginOn
      _endOn
      _deleted
      _fromEntityKey
      _toEntityKey
      displayName
    }
    properties
  }
}

Variables:

{
  "id": "<an edge id>",
  "label": "<edge label>",
  "filters": {
    "_id": "<a relationship id>",
    "_key": "<a relationship key>",
    "_type": "<a relationship type>",
    "_class": "<a relationship class>"
  }
}

Fetching the Count of Entities Via a _type and/or _class​

This query allows you to fetch the count of entities. The _id, _key, _type, or _class fields can be supplied as filters. This query only counts the latest versions of entities matching the filter criteria. This query requires two parameters:

  • filters: A set of vertex filters that describe the entities that are to be returned.
  • filterType: A FilterType (AND or OR).

If OR is specified as the filter type, any entity that has any class in the filter will be included in the count. By default, the query uses AND, which only includes entities that have all of the specified classes in the count.

This resolver uses the JSON scalar as the return type:

query testQuery($filters: VertexFilters, $filterType: FilterType) {
  entityCount(filters: $filters, filterType: $filterType)
}

Use field aliases to request the counts of multiple different entities:

query testQuery {
  Users: entityCount(filters: { _class: ["User"] }, filterType: "AND")
  Repos: entityCount(filters: { _class: ["CodeRepo"] }, filterType: "OR")
}

Example result:

{
  "User": 40,
  "CodeRepo": 153
}

Fetching the Count of All Types and Classes​

This query returns the entity counts for all types and classes. The following resolver uses the JSON scalar as the return type:

query testQuery {
  allEntityCounts
}

Example result:

{
  "typeCounts": {
    "iam_user": 12,
    "iam_managed_policy": 10,
    "iam_role_policy": 10
  },
  "classCounts": {
    "User": 12,
    "AccessPolicy": 20
  }
}

Fetching the Count of All Types With a Set of Classes​

The query below returns all types that have the specified classes. The query requires two parameters:

  • classes: An array of strings detailing which classes should be returned.
  • filterType: A FilterType (AND or OR).

If OR is specified as the filter type, any entity that has any class in the filter will be included in the count. By default, the query uses AND, which only includes entities that have all of the specified classes in the count.

This resolver uses the JSON scalar as the return type:

query testQuery ($classes: [String], filterType: FilterType) {
  typeCounts (classes: $classes, filterType: $filterType)
}

Example result:

{
  "iam_user": 12,
  "iam_managed_policy": 10,
  "iam_role_policy": 10
}

Listing Entities Via a _type and/or _class​

For fetching entities with specified filters. The _id, _key, _type and _class fields can be included in a J1QL query request.

This query has a deferred response flow and needs to be completed in three parts.

Contents