Skip to main content

List and Filter Atoms

Query multiple atoms with filtering, sorting, and pagination to find specific entities in the knowledge graph.

Query Structure​

query GetAtomsByType($type: atom_type!, $limit: Int!) {
  atoms(
    where: { type: { _eq: $type } }
    order_by: { created_at: desc }
    limit: $limit
  ) {
    term_id
    label
    image
    type
    created_at
  }
}

Variables​

{
  "type": "Person",
  "limit": 20
}

Interactive Examples​

Query

query GetAtomsByType($type: atom_type!, $limit: Int!) {
  atoms(
    where: { type: { _eq: $type } }
    order_by: { created_at: desc }
    limit: $limit
  ) {
    term_id
    label
    image
    type
    created_at
  }
}

Variables

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

Common Filter Patterns​

Filter by Type​

query GetPersonAtoms {
  atoms(
    where: { type: { _eq: Person } }
    limit: 10
  ) {
    term_id
    label
  }
}

Available types: Person, Organization, Thing

Filter by Creator​

query GetUserCreatedAtoms($creatorId: String!) {
  atoms(
    where: { creator_id: { _eq: $creatorId } }
    order_by: { created_at: desc }
  ) {
    term_id
    label
  }
}

Filter by Date Range​

query GetAtomsInRange($start: timestamptz!, $end: timestamptz!) {
  atoms(
    where: {
      created_at: { _gte: $start, _lte: $end }
    }
    order_by: { created_at: desc }
  ) {
    term_id
    label
    created_at
  }
}

Search by Label (Case-Insensitive)​

query SearchAtoms($search: String!) {
  atoms(
    where: { label: { _ilike: $search } }
    limit: 20
  ) {
    term_id
    label
  }
}

Note: Use % wildcards for partial matching: %ethereum%

Multiple Filters Combined​

query GetFilteredAtoms(
  $type: atom_type!
  $since: timestamptz!
  $search: String!
) {
  atoms(
    where: {
      _and: [
        { type: { _eq: $type } }
        { created_at: { _gte: $since } }
        { label: { _ilike: $search } }
      ]
    }
    order_by: { created_at: desc }
    limit: 20
  ) {
    term_id
    label
    type
    created_at
  }
}

Sorting Options​

By Creation Date​

atoms(order_by: { created_at: desc })

By Label (Alphabetical)​

atoms(order_by: { label: asc })

Multiple Sort Fields​

atoms(
  order_by: [
    { type: asc }
    { created_at: desc }
  ]
)

Pagination​

Offset-Based Pagination​

query GetAtomsPage($limit: Int!, $offset: Int!) {
  total: atoms_aggregate {
    aggregate {
      count
    }
  }

  atoms(
    limit: $limit
    offset: $offset
    order_by: { created_at: desc }
  ) {
    term_id
    label
  }
}

Variables:

{
  "limit": 20,
  "offset": 40
}

Use Cases​

Build Entity Directory​

List all atoms of a specific type:

const query = `
  query GetAllPersons($limit: Int!, $offset: Int!) {
    atoms(
      where: { type: { _eq: Person } }
      order_by: { label: asc }
      limit: $limit
      offset: $offset
    ) {
      term_id
      label
      image
    }
  }
`

User Dashboard​

Show atoms created by a user:

const query = `
  query GetMyAtoms($creatorId: String!) {
    atoms(
      where: { creator_id: { _eq: $creatorId } }
      order_by: { created_at: desc }
    ) {
      term_id
      label
      created_at
    }
  }
`

Recent Activity Feed​

Display recently created atoms:

const query = `
  query GetRecentAtoms($limit: Int!) {
    atoms(
      order_by: { created_at: desc }
      limit: $limit
    ) {
      term_id
      label
      created_at
      creator {
        label
      }
    }
  }
`

Performance Considerations​

  • Use specific filters to reduce result set size
  • Always include limit to prevent fetching too much data
  • Add order_by for consistent pagination
  • Use indexed fields (type, creator_id, created_at) for better performance

Best Practices​

  1. Always use variables for dynamic filter values
  2. Include limit to prevent over-fetching
  3. Use appropriate operators: _eq for exact matches, _ilike for searches
  4. Combine with aggregates when you need total counts
  5. Order results for consistent pagination