Skip to main content

Custom Queries

This page provides practical examples of common GraphQL queries for the Intuition API.

Best Practices​

  1. Use Fragments: Create reusable fragments for common fields
  2. Optimize Queries: Only request the fields you need
  3. Handle Errors: Always implement proper error handling
  4. Cache Strategically: Use React Query's caching capabilities
  5. Type Safety: Leverage generated types for better development experience

Basic Queries​

Fetching a Single Atom​

Use the primary key lookup for fetching a single atom by its term_id:

query GetAtom($termId: String!) {
  atom(term_id: $termId) {
    term_id
    label
    image
    type
    created_at
    creator {
      id
      label
    }
    value {
      thing { name description url }
      person { name description url }
      organization { name description url }
    }
  }
}

Fetching Triples​

Query triples with Hasura's where filtering:

query GetTriples($subjectId: String, $predicateLabel: String, $limit: Int = 20) {
  triples(
    where: {
      subject_id: { _eq: $subjectId }
      predicate: { label: { _ilike: $predicateLabel } }
    }
    order_by: { created_at: desc }
    limit: $limit
  ) {
    term_id
    subject {
      term_id
      label
    }
    predicate {
      term_id
      label
    }
    object {
      term_id
      label
    }
    created_at
  }
}

Fetching Signals​

Query signal events for a specific atom or account:

query GetSignals($accountId: String!, $limit: Int = 20) {
  signals(
    where: { account_id: { _eq: $accountId } }
    order_by: { created_at: desc }
    limit: $limit
  ) {
    id
    delta
    atom_id
    triple_id
    created_at
    account {
      label
    }
  }
}

Advanced Queries​

Use the search_term database function for text search:

query SearchAtoms($query: String!, $limit: Int = 20) {
  search_term(args: { query: $query }, limit: $limit) {
    term_id
    label
    image
    type
    creator {
      id
      label
    }
  }
}

Pagination​

Hasura uses offset-based pagination with limit and offset:

query GetAtomsPaginated($limit: Int!, $offset: Int!) {
  atoms_aggregate {
    aggregate {
      count
    }
  }
  atoms(
    limit: $limit
    offset: $offset
    order_by: { created_at: desc }
  ) {
    term_id
    label
    image
    type
    created_at
  }
}

React Query Hooks​

Using Generated Hooks​

import { useGetAtomQuery } from '@0xintuition/graphql'

function AtomViewer({ atomId }: { atomId: string }) {
  const { data, isLoading, error } = useGetAtomQuery({
    variables: { termId: atomId }
  })

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <div>
      <h1>{data?.atom?.label}</h1>
      <img src={data?.atom?.image} alt={data?.atom?.label} />
      <p>Type: {data?.atom?.type}</p>
    </div>
  )
}

Custom Hooks​

import { useQuery } from '@tanstack/react-query'
import { GraphQLClient } from 'graphql-request'
import { API_URL_PROD } from '@0xintuition/graphql'

const client = new GraphQLClient(API_URL_PROD)

function useCustomAtomQuery(termId: string) {
  return useQuery({
    queryKey: ['atom', termId],
    queryFn: () => client.request(`
      query GetAtom($termId: String!) {
        atom(term_id: $termId) {
          term_id
          label
          image
          type
        }
      }
    `, { termId }),
    enabled: !!termId
  })
}