Field Types

Grafbase supports the typical scalars you'd expect from any GraphQL implementation, as well as some custom ones.

The ID type represents a unique identifier for the data it represents. This field works in the same way as a String does.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Post', {
  id: scalar.id(),
})

The String type represents a UTF-8 character sequence.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Post', {
  title: scalar.string(),
})

The Int type represents a signed, 32-bit integer, which can be positive, negative, or 0.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Post', {
  likes: scalar.int(),
})

The Float type represents a signed, double-precision floating-point value, which can be positive, negative, or 0.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Post', {
  rating: scalar.float(),
})

The Boolean type represents a true or false value for non-nullable fields. Nullable fields default to null.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Post', {
  published: scalar.boolean(),
})

The Date type represents a date in the format of 2022-11-07 as described in RFC3339.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('User', {
  dob: scalar.date(),
})

The DateTime type represents a date and a time in RFC3339 format.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('User', {
  dob: scalar.datetime(),
})

The Email type represents an email address in the typical format of hello@grafbase.com, following the HTML Spec.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('User', {
  email: scalar.email(),
})

The IPAddress type represents a valid IPv4 or IPv6 address, with optional CIDR. IPv4 addresses are expected in quad-dotted notation, such as 123.123.123.123.

IPv6 addresses are expected in non-bracketed, colon-separated format, such as 1a2b:3c4b::1234:4567.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Activity', {
  ip: scalar.ipAddress(),
})

The Timestamp type represents a unix epoch time, in milliseconds.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Activity', {
  when: scalar.timestamp(),
})

The URL type represents a URL standard value, in the format of (but not limited to) http://, https://, wss://.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('User', {
  avatarUrl: scalar.url(),
})

The JSON type represents a JSON object that follows the ECMA-404 specification.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('Order', {
  metadata: scalar.json(),
})

The PhoneNumber scalar represents a E.164 phone number value, with or without the country code.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('User', {
  contactNo: scalar.phoneNumber(),
})

You can reference other types by passing that type as the field.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const profile = g.type('Profile', {
  address: scalar.string(),
})

const user = g.type('User', {
  profile: g.ref(profile),
})

If you're working with Resolvers you can use interfaces to represent data:

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const produce = g.interface('Produce', {
  name: scalar.string(),
  quantity: scalar.int(),
  price: scalar.float(),
  nutrients: scalar.string().optional().list().optional(),
})

g.type('Fruit', {
  isSeedless: scalar.boolean().optional(),
  ripenessIndicators: scalar.string().optional().list().optional(),
}).implements(produce)

If you're working with Resolvers you can use interfaces to represent data:

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const user = g.type('User', {
  name: scalar.string(),
  age: scalar.int().optional(),
})

const address = g.type('Address', {
  street: scalar.string().optional(),
})

g.union('UserOrAddress', { user, address })

Enums are a special type that are a set of allowed values.

To use an enum you must define the possible values in the config as well as a name:

import { graph } from '@grafbase/sdk'

const g = graph.Standalone()

g.enum('Status', ['PENDING_REVIEW', 'APPROVED'])

You can then use the enum as a field type:

import { graph } from '@grafbase/sdk'

const g = graph.Standalone()

const statusEnum = g.enum('Status', ['PENDING_REVIEW', 'APPROVED'])

g.type('Review', {
  status: g.enumRef(statusEnum),
})

You can even set default values for enumerations:

import { graph } from '@grafbase/sdk'

const g = graph.Standalone()

const statusEnum = g.enum('Status', ['PENDING_REVIEW', 'APPROVED'])

g.type('Review', {
  status: g.enumRef(statusEnum).default('PENDING_REVIEW'),
})

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

g.type('User', {
  name: scalar.string().optional(),
})

Grafbase supports nullable and non-nullable fields.

Nullable lists using the TS config are non-nullable by default, where as those using SDL config will need to use the ! at the end of fields.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const post = g.type('Post', {
  title: scalar.string(),
})

Grafbase supports using list values, as well as nullable and non-nullable lists.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const post = g.type('Post', {
  keywords: scalar.string().list(),
})

To allow nullable items in the list, using the TS config you must call .optional() on the base type. If you're using the SDL config, you can simply omit the ! from the list item type.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const post = g.type('Post', {
  keywords: scalar.string().optional().list(),
})

To make the list nullable itself, call .optional() on the list itself when using TS config, otherwise if using SDL you can simply omit the ! altogether.

import { graph, scalar } from '@grafbase/sdk'

const g = graph.Standalone()

const post = g.type('Post', {
  keywords: scalar.string().list().optional(),
})