Skip to main content

​
API

The Attio client SDK provides a typesafe way to query record data via GraphQL. There are two main functions for this. Which you choose to use is a design decision of your app.

​
runQuery

An imperative asynchronous function to query record data.

​
useQuery

A suspenseful hook to query record data.

​
Writing GraphQL Queries

When you run npx attio dev to develop your app, you will be prompted to Press "o" to open GraphQL Explorer.. If you do press o, it will open an instance of GraphiQL. GraphiQL will help you explore the schema as well as autocomplete your query as you type.
The GraphiQL instance is not hooked up to any data source!Pressing the ▶️ button to execute the query will return null if there are no errors.

​
Query composing example

​
Example Queries

query getCurrentUser {
  currentUser {
    id
    name
    email
  }
}

query getPersonEmailAddresses($recordId: String!) {
  person(id: $recordId) {
    email_addresses
  }
}

query getTeam($recordId: String!) {
  company(id: $recordId) {
    team {
      name {
        full_name
      }
      email_addresses
    }
  }
}

​
TypeScript Code-Gen

runQuery() and useQuery() will accept just a string as your query, but if you write your query in a separate file with the .graphql or .gql extension, you can then import your query into your TypeScript file. If you pass the imported query to these functions, your results will be strongly typed. The code generator will look for query files as long as you are runnning npx attio dev. Let’s look at an example: 
query getCurrentUser {
  currentUser {
    id
    name
    email
  }
}

​
Custom Attributes

Custom attributes can be loaded via GraphQL with their slug. The slug can be found under the kebab menu for the custom attribute in Workspace Settings. You can then use that slug in your GraphQL query like so:
get-bluesky.graphql
query getBlueSky($recordId: String!, $slug: String!) {
  person(id: $recordId) {
    attribute(slug: $slug) {
      __typename
      ... on TextValue {
        value
      }
    }
  }
}
You must include __typename and the ... on syntax to match the type of the attribute you are querying.
To please TypeScript, you will need check the __typename before reading the value. 
const {person} = useQuery(getBlueSky, {recordId, slug: "bluesky"})

const blueSkyValue = person?.attribute?.__typename === "TextValue" ? person.attribute.value : null

​
Advanced Usage

​
Fragments

Some queries can return multiple types of objects. The way this is handled in GraphQL is with fragments and by querying __typename and then switching on its value. The record query takes a record id and an object type and returns the matching object. Those variables happen to be exactly what the onTrigger() function on our record action is given. 
query getRecord($recordId: String!, $object: String!) {
  record(id: $recordId, object: $object) {
    id
    __typename
    url
    ...PersonFragment
    ...CompanyFragment
    ...DealFragment
    ...UserFragment
    ...WorkspaceFragment
  }
}

fragment PersonFragment on Person {
  personName: name {
    full_name
  }
}

fragment CompanyFragment on Company {
  companyName: name
}

fragment DealFragment on Deal {
  dealName: name
}

fragment UserFragment on UserRecord {
  person {
    ...PersonFragment
  }
}

fragment WorkspaceFragment on WorkspaceRecord {
  workspaceName: name
}