Search and Discovery

Discover atoms, triples, accounts, and collections using search, filters, and batch entity lookups.

Choose the GraphQL network explicitly

SDK reads use mainnet by default. Configure the endpoint once at startup; use API_URL_DEV for Intuition Testnet or API_URL_PROD for Mainnet:

import { configureSdk } from '@0xintuition/sdk'
import { API_URL_DEV } from '@0xintuition/graphql'

configureSdk({ apiUrl: API_URL_DEV })

Global Search
Searching Atoms
Searching Triples
Advanced Queries

Global Search

Search across all entity types (atoms, accounts, triples, collections) with a single query.

Function Signature

function globalSearch(
  query: string,
  options: GlobalSearchOptions
): Promise<GlobalSearchResults | null>

Parameters

Parameter	Type	Description	Required
`query`	`string`	Search query text	Yes
`options`	`GlobalSearchOptions`	Search limits per type	Yes

GlobalSearchOptions

type GlobalSearchOptions = {
  atomsLimit?: number       // Default: 5
  accountsLimit?: number    // Default: 5
  triplesLimit?: number     // Default: 5
  collectionsLimit?: number // Default: 5
}

Basic Example

import { globalSearch } from '@0xintuition/sdk'

const results = await globalSearch('ethereum', {})

if (results) {
  console.log('Atoms:', results.atoms.length)
  console.log('Accounts:', results.accounts.length)
  console.log('Triples:', results.triples.length)
  console.log('Collections:', results.collections.length)
}

Advanced Example

Search with custom limits:

import { globalSearch } from '@0xintuition/sdk'

async function searchWithLimits(query: string) {
  const results = await globalSearch(query, {
    atomsLimit: 20,      // Get up to 20 atoms
    accountsLimit: 10,   // Get up to 10 accounts
    triplesLimit: 15,    // Get up to 15 triples
    collectionsLimit: 5, // Get up to 5 collections
  })

  if (!results) {
    console.log('Search failed or returned no results')
    return
  }

  // Display atoms
  console.log('\n=== Atoms ===')
  results.atoms.forEach(atom => {
    console.log(`${atom.label ?? 'Unnamed atom'} (ID: ${atom.term_id})`)
  })

  // Display triples
  console.log('\n=== Triples ===')
  results.triples.forEach(triple => {
    console.log(
      `${triple.subject?.label ?? 'Unknown subject'} ` +
      `${triple.predicate?.label ?? 'Unknown predicate'} ` +
      `${triple.object?.label ?? 'Unknown object'}`
    )
  })

  return results
}

// Usage
await searchWithLimits('blockchain')

Common Use Cases

Search for Specific Entity Type

// Search only for atoms
const results = await globalSearch('defi', {
  atomsLimit: 50,
  accountsLimit: 0,
  triplesLimit: 0,
  collectionsLimit: 0,
})

if (!results) throw new Error('Search failed')

console.log('DeFi atoms:', results.atoms)

Build Autocomplete

async function autocomplete(input: string) {
  if (input.length < 2) return []

  const results = await globalSearch(input, {
    atomsLimit: 10,
    accountsLimit: 5,
    triplesLimit: 0,
    collectionsLimit: 0,
  })

  if (!results) return []

  return [
    ...results.atoms.map(a => ({ type: 'atom', label: a.label, id: a.id })),
    ...results.accounts.map(a => ({ type: 'account', label: a.label, id: a.id })),
  ]
}

// Usage in React
const suggestions = await autocomplete('block')

Search and Display Details

import { globalSearch, getAtomDetails } from '@0xintuition/sdk'

async function searchAndDisplay(query: string) {
  const results = await globalSearch(query, { atomsLimit: 5 })

  if (!results || results.atoms.length === 0) {
    console.log('No atoms found')
    return
  }

  // Get detailed information for first atom
  const firstAtom = results.atoms[0]
  const details = await getAtomDetails(firstAtom.term_id)

  if (!details) {
    console.log('Atom details were not found')
    return
  }

  const vault = details.term?.vaults[0]

  console.log('First result:', firstAtom.label)
  console.log('Creator:', details.creator?.label ?? details.creator_id)
  console.log('Vault shares:', vault?.total_shares)
}

Return Type

type GlobalSearchResults = {
  atoms: Array<{
    id: string
    label: string
    // Additional atom fields
  }>
  accounts: Array<{
    id: string
    label: string
    // Additional account fields
  }>
  triples: Array<{
    id: string
    subject: { id: string, label: string }
    predicate: { id: string, label: string }
    object: { id: string, label: string }
    // Additional triple fields
  }>
  collections: Array<{
    id: string
    label: string
    // Additional collection fields
  }>
}

Error Handling

The function returns null on error:

const results = await globalSearch('query', {})

if (!results) {
  console.error('Search failed')
  return
}

// Use results
console.log('Found', results.atoms.length, 'atoms')

Searching Atoms

Search for atoms using the global search function and other query methods.

Using Global Search

import { globalSearch } from '@0xintuition/sdk'

const results = await globalSearch('blockchain', {
  atomsLimit: 20,
  accountsLimit: 0,    // Skip accounts
  triplesLimit: 0,     // Skip triples
  collectionsLimit: 0, // Skip collections
})

if (!results) throw new Error('Search failed')

console.log('Found atoms:', results.atoms.length)
results.atoms.forEach(atom => {
  console.log(`- ${atom.label ?? 'Unnamed atom'} (${atom.term_id})`)
})

Using findAtomIds

Find atom IDs for known atom data.

Basic Example

import { findAtomIds } from '@0xintuition/sdk'

const atomData = ['TypeScript', 'JavaScript', 'Python']

const atoms = await findAtomIds(atomData)

atoms.forEach(atom => {
  console.log(`${atom.data}: ${atom.term_id}`)
})

atomData
  .filter(data => !atoms.some(atom => atom.data === data))
  .forEach(data => {
    console.log(`${data}: not found`)
  })

Searching Triples

Search for triple statements using various methods.

Using Global Search

import { globalSearch } from '@0xintuition/sdk'

const results = await globalSearch('follows', {
  atomsLimit: 0,
  accountsLimit: 0,
  triplesLimit: 20,    // Focus on triples
  collectionsLimit: 0,
})

if (!results) throw new Error('Search failed')

console.log('Found triples:', results.triples.length)
results.triples.forEach(triple => {
  console.log(
    `${triple.subject?.label ?? 'Unknown subject'} ` +
    `${triple.predicate?.label ?? 'Unknown predicate'} ` +
    `${triple.object?.label ?? 'Unknown object'}`
  )
})

Using findTripleIds

Find triple IDs for specific atom combinations.

import { calculateAtomId, findTripleIds } from '@0xintuition/sdk'
import { toHex, type Address, type Hex } from 'viem'

// Replace this illustrative address with the wallet whose positions you want returned.
const walletAddress: Address = '0x1111111111111111111111111111111111111111'
const tripleCombinations: Array<[Hex, Hex, Hex]> = [
  [
    calculateAtomId(toHex('TypeScript')),
    calculateAtomId(toHex('isA')),
    calculateAtomId(toHex('Programming Language')),
  ],
  [
    calculateAtomId(toHex('Python')),
    calculateAtomId(toHex('isA')),
    calculateAtomId(toHex('Programming Language')),
  ],
]

const triples = await findTripleIds(
  walletAddress,
  tripleCombinations
)

triples.forEach(triple => {
  console.log('Found triple:', triple.term_id)
})

Advanced Queries

Advanced search helpers include batch entity lookup functions.

findAtomIds

Find atom IDs for a batch of atom data strings.

Function Signature

function findAtomIds(
  atomDataArray: string[]
): Promise<Array<{ data: string, term_id: string }>>

Basic Example

import { findAtomIds } from '@0xintuition/sdk'

const data = ['TypeScript', 'JavaScript', 'Python', 'Rust', 'Go']

const atoms = await findAtomIds(data)

atoms.forEach(atom => {
  console.log(`Found ${atom.data}: ${atom.term_id}`)
})

data
  .filter(item => !atoms.some(atom => atom.data === item))
  .forEach(item => {
    console.log(`Missing ${item}: not found`)
  })

Advanced Example

Check existence before creating:

import {
  findAtomIds,
  createAtomFromString,
  type WriteConfig,
} from '@0xintuition/sdk'
import { parseEther } from 'viem'

async function createMissingAtoms(config: WriteConfig, atomData: string[]) {
  // Find existing atoms
  const atoms = await findAtomIds(atomData)

  // findAtomIds returns only matches, so diff the inputs against their data.
  const missing = atomData.filter(
    data => !atoms.some(atom => atom.data === data)
  )

  if (missing.length === 0) {
    console.log('All atoms already exist')
    return atoms
  }

  console.log(`Creating ${missing.length} missing atoms...`)

  // Create missing atoms
  for (const data of missing) {
    const created = await createAtomFromString(
      config,
      data,
      parseEther('0.01')
    )
    atoms.push({ data, term_id: created.state.termId })
    console.log(`Created: ${data}`)
  }

  return atoms
}

findTripleIds

Find triple IDs for specific atom combinations.

Function Signature

function findTripleIds(
  walletAddress: Address,
  tripleCombinations: Array<[Hex, Hex, Hex]>
): Promise<Array<TripleWithIds>>

Basic Example

import { calculateAtomId, findTripleIds } from '@0xintuition/sdk'
import { toHex, type Address, type Hex } from 'viem'

// Replace this illustrative address with the wallet whose positions you want returned.
const walletAddress: Address = '0x1111111111111111111111111111111111111111'
const combinations: Array<[Hex, Hex, Hex]> = [
  [
    calculateAtomId(toHex('TypeScript')),
    calculateAtomId(toHex('isA')),
    calculateAtomId(toHex('Programming Language')),
  ],
  [
    calculateAtomId(toHex('Python')),
    calculateAtomId(toHex('isA')),
    calculateAtomId(toHex('Programming Language')),
  ],
]

const triples = await findTripleIds(
  walletAddress,
  combinations
)

triples.forEach(triple => {
  console.log('Found triple:', triple.term_id)
  console.log('  Positions:', triple.positions.length)
})

Advanced Example

Check and create triples:

import {
  findTripleIds,
  createTripleStatement,
  type WriteConfig,
} from '@0xintuition/sdk'
import { parseEther, type Hex } from 'viem'

async function ensureTriples(
  config: WriteConfig,
  combinations: Array<[Hex, Hex, Hex]>
) {
  const account = config.walletClient.account
  if (!account) throw new Error('Wallet client account is required')

  // Check which triples exist
  const found = await findTripleIds(
    account.address,
    combinations
  )

  // Create missing triples
  for (let i = 0; i < combinations.length; i++) {
    const [subject, predicate, object] = combinations[i]
    const existing = found.find(
      triple =>
        triple.subject_id === subject &&
        triple.predicate_id === predicate &&
        triple.object_id === object
    )

    if (!existing) {
      console.log(`Creating triple: ${subject.slice(0, 10)}...`)

      await createTripleStatement(config, {
        args: [
          [subject],
          [predicate],
          [object],
          [parseEther('0.1')],
        ],
        value: parseEther('0.1'),
      })

      console.log('Created')
    } else {
      console.log('Already exists:', existing.term_id)
    }
  }
}

Batch Processing

Process large datasets efficiently:

import { findAtomIds } from '@0xintuition/sdk'

async function processInBatches<T>(
  items: T[],
  batchSize: number,
  processor: (batch: T[]) => Promise<void>
) {
  for (let i = 0; i < items.length; i += batchSize) {
    const batch = items.slice(i, i + batchSize)
    await processor(batch)
  }
}

// Usage
const allData = ['atom1', 'atom2', /* ... hundreds more */]

await processInBatches(allData, 100, async (batch) => {
  const atoms = await findAtomIds(batch)
  console.log(`Processed ${atoms.length} atoms`)
})

Complete Examples

See working examples in the SDK Examples section

Next Steps

Working with Atoms - Create and manage atoms
Working with Triples - Build relationships
SDK Integrations - Use with React

Table of Contents​

Global Search​

Function Signature​

Parameters​

GlobalSearchOptions​

Basic Example​

Advanced Example​

Common Use Cases​

Search for Specific Entity Type​

Build Autocomplete​

Search and Display Details​

Return Type​

Error Handling​

Searching Atoms​

Using Global Search​

Using findAtomIds​

Basic Example​

Searching Triples​

Using Global Search​

Using findTripleIds​

Advanced Queries​

findAtomIds​

Function Signature​

Basic Example​

Advanced Example​

findTripleIds​

Function Signature​

Basic Example​

Advanced Example​

Batch Processing​

Complete Examples​

Next Steps​

Table of Contents

Global Search

Function Signature

Parameters

GlobalSearchOptions

Basic Example

Advanced Example

Common Use Cases

Search for Specific Entity Type

Build Autocomplete

Search and Display Details

Return Type

Error Handling

Searching Atoms

Using Global Search

Using findAtomIds

Basic Example

Searching Triples

Using Global Search

Using findTripleIds

Advanced Queries

findAtomIds

Function Signature

Basic Example

Advanced Example

findTripleIds

Function Signature

Basic Example

Advanced Example

Batch Processing

Complete Examples

Next Steps