Skip to main content

Single Atom Query

Fetch detailed information about a specific atom using its term ID. This is the most efficient way to retrieve atom data using a primary key lookup.

Query Structure​

query GetAtom($id: String!) {
  atom(term_id: $id) {
    term_id
    data
    label
    image
    emoji
    type
    created_at
    creator {
      id
      label
      image
    }
  }
}

Variables​

{
  "id": "0x57d94c116a33bb460428eced262b7ae2ec6f865e7aceef6357cec3d034e8ea21"
}

Expected Response​

{
  "data": {
    "atom": {
      "term_id": "0x57d94c116a33bb460428eced262b7ae2ec6f865e7aceef6357cec3d034e8ea21",
      "data": "ipfs://QmYx8C3kNN1sFSx5b...",
      "label": "Ethereum",
      "image": "ipfs://QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy",
      "emoji": "⟠",
      "type": "Thing",
      "created_at": "2024-01-15T10:30:00Z",
      "creator": {
        "id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "label": "Alice",
        "image": "ipfs://..."
      }
    }
  }
}

Interactive Example​

Query

query GetAtom($id: String!) {
  atom(term_id: $id) {
    term_id
    data
    label
    image
    emoji
    type
    created_at
    creator {
      id
      label
      image
    }
  }
}

Variables

Click "Run Query" to execute the GraphQL query and see results

Use Cases​

Display Atom Details​

Fetch complete atom information for display in a UI:

import { GraphQLClient } from 'graphql-request'
import { API_URL_PROD } from '@0xintuition/graphql'

const client = new GraphQLClient(API_URL_PROD)

const query = `
  query GetAtom($id: String!) {
    atom(term_id: $id) {
      term_id
      label
      image
      type
    }
  }
`

const atomId = '0x...'
const data = await client.request(query, { id: atomId })
console.log(data.atom)

Verify Atom Existence​

Check if an atom exists before performing operations:

const query = `
  query CheckAtomExists($id: String!) {
    atom(term_id: $id) {
      term_id
    }
  }
`

const data = await client.request(query, { id: atomId })
if (data.atom) {
  console.log('Atom exists')
} else {
  console.log('Atom not found')
}

Get Creator Information​

Fetch atom with creator details for attribution:

const query = `
  query GetAtomWithCreator($id: String!) {
    atom(term_id: $id) {
      term_id
      label
      creator {
        id
        label
        image
      }
    }
  }
`

Performance Considerations​

  • Primary key lookup: Most efficient way to fetch a single atom
  • Index usage: Term ID queries use the primary index
  • Field selection: Only request fields you need to minimize response size

Common Errors​

Atom not found: Returns null if the term ID doesn't exist:

{
  "data": {
    "atom": null
  }
}

Invalid term ID format: Ensure the ID is a valid hex string starting with "0x".

Best Practices​

  1. Use variables for the term ID instead of hardcoding
  2. Request only needed fields to minimize response size
  3. Cache results if the same atom is queried frequently
  4. Handle null responses when the atom doesn't exist

See Also​