Skip to main content

Global Node IDs

In GraphQL API id field returns a unique global node identifier instead of numeric value like in our REST API. This is useful for querying a node by its unique identifier.

  1. Finding object's node ID

You can navigate GraphQL API without knowing node IDs using connections.

query {
  me {
    id
    username
    accounts(first: 10) {
      nodes {
        id
      }
    }
  }
}

This query will return currently logged in user's node ID and first 10 accounts' node IDs that user has access to.

  1. Finding object type in GraphQL

In this example, the id value is TjAwNFVzZXIzMzkwMA. You can use this value to query the same object in GraphQL.

You'll need to know the object's type first, though. You can check the type with a simple GraphQL query:

query {
  node(id: "TjAwNFVzZXIzMzkwMA") {
    __typename
  }
}

This type of query—that is, finding the node by ID—is known as a "direct node lookup."

When you run this query, you'll see that the __typename is User.

  1. Do a direct node lookup in GraphQL

Once you've confirmed the type, you can use an inline fragment to access the object by its ID and return additional data. In this example, we define the fields on User that we'd like to query:

{
  node(id: "TjAwNFVzZXIzMzkwMA") {
    __typename
    ... on User {
      username
    }
  }
}

This type of query is the standard approach for looking up an object by its global node ID.

Querying object by its numeric ID​

You can still query for objects by their numeric IDs with helper queries.

query {
  getCrawl(id: 123) {
    id
    rawID
  }
}

Would return the crawl with ID where id field would return global node ID and rawID would returned stringified numeric ID.

Building Global Node ID​

Global Node ID is url-safe base64 encoded string of concatenated type and id fields.

For example to build global node ID for User object with ID 123 you can do this:

N + len("User") + "User" + 123
base64("N004User123") -> "TjAwNFVzZXIxMjM"

or for Project with ID 456:

N + len("Project") + "Project" + 456
base64("N007Project456") -> "TjAwN1Byb2plY3Q0NT"

or for Crawl with ID 78999:

N + len("Crawl") + "Crawl" + 78999
base64("N005Crawl78999") -> "TjAwNUNyYXdsNzg5OTk"