Field Types

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

ID

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

import { g } from '@grafbase/sdk'

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

String

The String type represents a UTF-8 character sequence.

import { g } from '@grafbase/sdk'

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

Int

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

import { g } from '@grafbase/sdk'

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

Float

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

import { g } from '@grafbase/sdk'

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

Boolean

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

import { g } from '@grafbase/sdk'

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

Date

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

import { g } from '@grafbase/sdk'

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

DateTime

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

import { g } from '@grafbase/sdk'

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

Email

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

import { g } from '@grafbase/sdk'

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

IPAdress

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 { g } from '@grafbase/sdk'

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

Timestamp

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

import { g } from '@grafbase/sdk'

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

URL

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

import { g } from '@grafbase/sdk'

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

JSON

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

import { g } from '@grafbase/sdk'

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

PhoneNumber

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

import { g } from '@grafbase/sdk'

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

References

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

import { g } from '@grafbase/sdk'

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

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

Interfaces

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

import { g } from '@grafbase/sdk'

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

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

Unions

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

import { g } from '@grafbase/sdk'

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

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

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

Enumerations

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 { g } from '@grafbase/sdk'

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

You can then use the enum as a field type:

import { g } from '@grafbase/sdk'

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

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

You can even set default values for enumerations:

import { g } from '@grafbase/sdk'

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

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

Optional fields

import { g } from '@grafbase/sdk'

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

Nullability

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 { g } from '@grafbase/sdk'

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

Lists

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

import { g } from '@grafbase/sdk'

const post = g.type('Post', {
  keywords: g.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 { g } from '@grafbase/sdk'

const post = g.type('Post', {
  keywords: g.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 { g } from '@grafbase/sdk'

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