Grafbase Documentation

https://grafbase.com/docs
Admin
Grafbase is the fastest GraphQL Gateway for managing large-scale federated graphs. Compose unified...
Tokens:56,599
Snippets:162
Trust Score:9.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Grafbase Gateway

Source: https://grafbase.com/docs/gateway/installation

Installs the Grafbase Gateway by downloading and executing a script. This is the primary method for getting the gateway onto your system.

```shell
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

--------------------------------

### Install Grafbase Gateway

Source: https://grafbase.com/docs/self-hosted-gateway

Installs the Grafbase Gateway by downloading and executing a script. This is the primary method for getting the gateway onto your system.

```shell
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

--------------------------------

### Install Grafbase Gateway

Source: https://grafbase.com/docs/gateway/configuration

Installs the Grafbase Gateway by downloading and executing a script. This is the primary method for getting the gateway onto your system.

```shell
curl -fsSL https://grafbase.com/downloads/gateway | bash
```

--------------------------------

### Start Grafbase Gateway in Hybrid Mode

Source: https://grafbase.com/docs/gateway/installation

Starts the Grafbase Gateway in hybrid mode, fetching the federated graph from the Grafbase platform. Requires an organization access token and a graph reference.

```shell
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

--------------------------------

### Start Grafbase Gateway in Hybrid Mode

Source: https://grafbase.com/docs/self-hosted-gateway

Starts the Grafbase Gateway in hybrid mode, fetching the federated graph from the Grafbase platform. Requires an organization access token and a graph reference.

```shell
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

--------------------------------

### Start Grafbase Gateway in Air-gapped Mode

Source: https://grafbase.com/docs/gateway/installation

Starts the Grafbase Gateway in air-gapped (self-hosted) mode, using a local federated graph schema file. The gateway monitors this file for changes.

```shell
./grafbase-gateway \
  --config /path/to/grafbase.toml \
  --schema /path/to/federated-schema.graphql \
  --listen-address 127.0.0.1:4000
```

--------------------------------

### Start Grafbase Gateway in Air-gapped Mode

Source: https://grafbase.com/docs/self-hosted-gateway

Starts the Grafbase Gateway in air-gapped (self-hosted) mode, using a local federated graph schema file. The gateway monitors this file for changes.

```shell
./grafbase-gateway \
  --config /path/to/grafbase.toml \
  --schema /path/to/federated-schema.graphql \
  --listen-address 127.0.0.1:4000
```

--------------------------------

### Start Grafbase Gateway in Hybrid Mode

Source: https://grafbase.com/docs/gateway/configuration

Starts the Grafbase Gateway in hybrid mode, fetching the federated graph from the Grafbase platform. Requires an organization access token and a graph reference.

```shell
GRAFBASE_ACCESS_TOKEN=token ./grafbase-gateway \
  --config grafbase.toml \
  --graph-ref graph@branch
```

--------------------------------

### Grafbase CLI Documentation Links

Source: https://grafbase.com/docs/gateway/performance/entity-caching

Provides links to key documentation sections for the Grafbase CLI, including installation and commands.

```APIDOC
Grafbase CLI Documentation:

Installation:
  - /docs/cli/installation

Commands:
  - (Details on specific commands would be listed here)
```

--------------------------------

### Install Grafbase CLI with Curl

Source: https://grafbase.com/docs/cli/installation

Installs the Grafbase CLI using curl. This command fetches the latest version of the CLI script and executes it. A specific version can be installed by appending the version number to the bash command.

```shell
curl -fsSL https://grafbase.com/downloads/cli | bash
```

```shell
curl -fsSL https://grafbase.com/downloads/cli | bash -s 0.86.1
```

--------------------------------

### Start Grafbase Gateway in Air-gapped Mode

Source: https://grafbase.com/docs/gateway/configuration

Starts the Grafbase Gateway in air-gapped (self-hosted) mode, using a local federated graph schema file. The gateway monitors this file for changes.

```shell
./grafbase-gateway \
  --config /path/to/grafbase.toml \
  --schema /path/to/federated-schema.graphql \
  --listen-address 127.0.0.1:4000
```

--------------------------------

### Example: Publish Schema from a File

Source: https://grafbase.com/docs/cli/commands/publish

This example shows how to publish a subgraph schema by providing the path to a local schema file using the `--schema` option. It also specifies the subgraph name, URL, and a commit message.

```bash
grafbase publish \
    --name users \
    --url http://localhost:4000/graphql \
    --message "Adds name field to the User type" \
    --schema users.graphql \
    my-org/my-graph@main
```

--------------------------------

### Gateway Hooks Configuration Example

Source: https://grafbase.com/docs/gateway/configuration/hooks

Example TOML configuration for the Grafbase Gateway's hooks extension. This defines the path to the WASM module and various runtime settings.

```toml
[extensions.my-hooks] # my-hooks is the name of your hooks project
path = "path/to/build"
networking = false
stdout = false
stderr = false
environment_variables = false
max_pool_size = 1000
config = {}
```

--------------------------------

### Install Grafbase CLI in GitHub Actions

Source: https://grafbase.com/docs/cli/installation

Demonstrates how to install the Grafbase CLI within a GitHub Actions workflow. It utilizes the official `grafbase/install-grafbase-cli` action for seamless integration into CI/CD pipelines.

```yaml
- name: Install the Grafbase CLI
  uses: grafbase/install-grafbase-cli@v1
```

--------------------------------

### Start Grafbase MCP Server CLI

Source: https://grafbase.com/docs/gateway/mcp

Command to start the Grafbase MCP server using the Grafbase CLI. This command initiates a local MCP server that listens for requests, making your data accessible via natural language interfaces.

```shell
npx grafbase mcp <url>
```

--------------------------------

### Install Grafbase CLI with Curl

Source: https://grafbase.com/docs/grafbase-cli

Installs the Grafbase CLI using curl. This command fetches the latest version of the CLI script and executes it. A specific version can be installed by appending the version number to the bash command.

```shell
curl -fsSL https://grafbase.com/downloads/cli | bash
```

```shell
curl -fsSL https://grafbase.com/downloads/cli | bash -s 0.86.1
```

--------------------------------

### Cursor MCP Configuration

Source: https://grafbase.com/docs/gateway/mcp

Example JSON configuration file for integrating a Grafbase MCP server with Cursor. This setup allows Cursor to connect to and utilize the MCP endpoint provided by Grafbase.

```json
{
  "mcpServers": {
    "my-graphql-api": {
      "url": "http://127.0.0.1:5000/mcp"
    }
  }
}
```

--------------------------------

### Install Grafbase CLI in GitHub Actions

Source: https://grafbase.com/docs/grafbase-cli

Demonstrates how to install the Grafbase CLI within a GitHub Actions workflow. It utilizes the official `grafbase/install-grafbase-cli` action for seamless integration into CI/CD pipelines.

```yaml
- name: Install the Grafbase CLI
  uses: grafbase/install-grafbase-cli@v1
```

--------------------------------

### Grafbase Check Command Examples

Source: https://grafbase.com/docs/cli/commands/check

Illustrates how to use the Grafbase CLI 'check' command with different scenarios, including checking a schema file and checking from standard input.

```cli
grafbase check --name my-subgraph --schema my-subgraph.graphql my-org/my-graph@main

grafbase introspect http://localhost:4000/graphql | grafbase check --name my-subgraph my-org/my-graph@main
```

--------------------------------

### Grafbase Gateway Documentation

Source: https://grafbase.com/docs/gateway/security/authorization

Information regarding the Grafbase Gateway, including installation, deployment, extensions, MCP, observability, performance, security, arguments, configuration, errors, and telemetry.

```APIDOC
Grafbase Gateway:
  Sections:
  - Installation: /docs/gateway/installation
  - Deployment: (Implicitly covered)
  - Extensions: /docs/gateway/extensions
  - MCP (Managed Cloud Platform): /docs/gateway/mcp
  - Observability: /docs/gateway/observability
  - Performance: (General topic)
  - Security: /docs/gateway/security
  - Arguments: /docs/gateway/arguments
  - Configuration: (General topic)
  - Errors: /docs/gateway/errors
  - Telemetry: (General topic)

  This documentation covers the setup, configuration, and operational aspects of the Grafbase Gateway, a core component for managing GraphQL APIs.
```

--------------------------------

### Grafbase CLI Documentation

Source: https://grafbase.com/docs/gateway/security/authorization

Details on the Grafbase Command Line Interface (CLI), including installation and available commands for managing Grafbase projects.

```APIDOC
Grafbase CLI:
  Sections:
  - Installation: /docs/cli/installation
  - Commands: (Implicitly covered)

  This section covers the installation and usage of the Grafbase CLI, a tool for interacting with Grafbase services and managing projects.
```

--------------------------------

### Install Grafbase CLI with NPM

Source: https://grafbase.com/docs/grafbase-cli

Installs the Grafbase CLI using npm, the Node Package Manager. This is a convenient method for developers who already have Node.js and npm set up in their environment.

```shell
npm install grafbase
```

--------------------------------

### Install Grafbase CLI with NPM

Source: https://grafbase.com/docs/cli/installation

Installs the Grafbase CLI using npm, the Node Package Manager. This is a convenient method for developers who already have Node.js and npm set up in their environment.

```shell
npm install grafbase
```

--------------------------------

### APQ: Executing and Registering Queries via GET Request

Source: https://grafbase.com/docs/gateway/performance/automatic-persisted-queries

Provides `curl` examples for interacting with Grafbase Gateway using GET requests for Automatic Persisted Queries. It shows how to execute a persisted query and how to register a new query by including both the query string and its hash.

```shell
curl --get 'http://localhost:4000/graphql' \
  --data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5"}}'
```

```shell
curl --get 'http://localhost:4000/graphql' \
  --data-urlencode 'query=query { __typename }' \
  --data-urlencode 'extensions={"persistedQuery":{"version":1,"sha256Hash":"4ef8d269e7944ef2cd6554ecb3d73164546945cf935806933448905abec554e5"}}'
```

--------------------------------

### Grafbase Gateway Documentation Links

Source: https://grafbase.com/docs/gateway/performance/entity-caching

Provides links to key documentation sections for the Grafbase Gateway, covering installation, extensions, MCP, observability, security, arguments, configuration, errors, telemetry, and platform aspects.

```APIDOC
Grafbase Gateway Documentation:

Installation:
  - /docs/gateway/installation

Extensions:
  - /docs/gateway/extensions

MCP:
  - /docs/gateway/mcp

Observability:
  - /docs/gateway/observability

Security:
  - /docs/gateway/security

Arguments:
  - /docs/gateway/arguments

Configuration:
  - /docs/gateway/configuration

Errors:
  - /docs/gateway/errors

Telemetry:
  - /docs/gateway/telemetry
```

--------------------------------

### Apollo Server Entity Resolver Example

Source: https://grafbase.com/docs/federation/overview

Provides an example of an entity resolver function (__resolveReference) in Apollo Server. This function is required for objects annotated with the @key directive to retrieve the entity based on its key.

```JavaScript
const resolvers = {
  User: {
    __resolveReference(object) {
      return fetchUserById(object.id) // fetchUserById is a hypothetical function that retrieves a User by their ID
    },
  },
}
```

--------------------------------

### Example: Introspect and Publish Schema from Standard Input

Source: https://grafbase.com/docs/cli/commands/publish

This example demonstrates how to introspect a remote GraphQL endpoint and pipe the schema directly to the `grafbase publish` command. It includes specifying the subgraph name, URL, and a commit message.

```bash
grafbase introspect http://localhost:4000/graphql \
    | grafbase publish \
        --name users \
        --url http://localhost:4000/graphql \
        --message "Adds name field to the User type" \
        my-org/my-graph@main
```

--------------------------------

### Grafbase Enterprise Platform Helm Charts

Source: https://grafbase.com/docs/platform/self-hosting

Information regarding the distribution of the Grafbase Enterprise Platform via Helm charts for Kubernetes installations.

```APIDOC
Grafbase Enterprise Platform Helm Charts:

- Distribution: Via Helm charts installable on any Kubernetes cluster.
- Customization: Helm charts allow selection of desired components from the Enterprise Platform.
- Access: Credentials for accessing Helm charts are provided upon contacting Grafbase.
```

--------------------------------

### Example Synchronous Custom Check Webhook Implementation

Source: https://grafbase.com/docs/platform/schema-checks

An example implementation of a synchronous custom check webhook using Node.js and Express. It parses the GraphQL schema, collects input types, and checks for specific mutation field patterns.

```javascript
const express = require('express');
const { parse, visit } = require('graphql');
const app = express();
app.use(express.json());

app.post('/custom-check', (req, res) => {
  const { subgraph } = req.body;
  const diagnostics = [];

  try {
    const parsedSchema = parse(subgraph.schema);
    const inputTypes = new Set();
    const mutationFields = [];

    // Collect all input types
    visit(parsedSchema, {
      InputObjectTypeDefinition(node) {
        inputTypes.add(node.name.value);
      }
    });

    // Check mutation fields
    visit(parsedSchema, {
      ObjectTypeDefinition(node) {
        if (node.name.value === 'Mutation') {
          node.fields.forEach(field => {
            // Example: Check for forbidden prefixes/suffixes on mutation fields
            if (field.name.value.startsWith('mutation') || field.name.value.endsWith('Mutation')) {
              diagnostics.push({
                message: `Mutation field \`${field.name.value}` has a forbidden prefix or suffix.`, 
                severity: "ERROR"
              });
            }
          });
        }
      }
    });

    // Add more checks here based on your requirements

    res.status(200).json({ diagnostics });
  } catch (error) {
    res.status(500).json({ diagnostics: [{ message: `Webhook failed: ${error.message}`, severity: "ERROR" }] });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Custom check webhook listening on port ${PORT}`);
});
```

--------------------------------

### Grafbase CLI Usage for Schema Checks

Source: https://grafbase.com/docs/platform/schema-checks

Demonstrates how to use the `grafbase check` command, including authentication for CI environments and generating schema files for analysis.

```bash
# Interactive login
grafbase login

# Running checks interactively
grafbase check

# Using grafbase check in CI with an access token
# Replace YOUR_GRAFBASE_ACCESS_TOKEN with your actual token
GRAFBASE_API_KEY=YOUR_GRAFBASE_ACCESS_TOKEN grafbase check --schema ./grafbase/schema.graphql

# Generating schema files for analysis (e.g., for CI)
grafbase introspect --dev --schema ./grafbase/schema.graphql
```

--------------------------------

### Example GraphQL Operation for Exclusion

Source: https://grafbase.com/docs/platform/schema-checks

An example GraphQL query document that can be used to exclude specific operations from Operation Checks based on its operation name.

```graphql
query JapaneseProducts {
  products(filter: { madeIn: "JP" }) {
    id
    name
  }
}
```

--------------------------------

### Grafbase Federation Documentation

Source: https://grafbase.com/docs/gateway/security/authorization

Information on Grafbase's support for GraphQL Federation, including overview and directives.

```APIDOC
Grafbase Federation:
  Sections:
  - Overview: /docs/federation/overview
  - Directives: /docs/federation/graphql-directives

  This documentation explains how Grafbase supports GraphQL Federation, including the use of specific directives for schema composition and management.
```

--------------------------------

### GraphQL Complexity Calculation Example

Source: https://grafbase.com/docs/gateway/security/operation-limits

Demonstrates the calculation of GraphQL operation complexity, factoring in field count, depth, and pagination arguments. This example shows a query with a calculated complexity of 18.

```graphql
query {
  # total: 18
  products(limit: 2) {
    # (Nested: 2 + 1 + 1 + 1 + (author: 2 + 1 + 1)) * limit: 2 = 18
    id # scalar: 1
    title # scalar: 1
    price # scalar: 1
    brand {
      # nested: 4 (2 + 1 + 1)
      id # scalar: 1
      name # scalar: 1
    }
  }
}
```

--------------------------------

### GraphQL Depth Calculation Example

Source: https://grafbase.com/docs/gateway/security/operation-limits

Illustrates how the nesting depth of a GraphQL query is calculated. Each level of nesting, including fields within fragments, contributes to the total depth. This example shows a query with a depth of 3.

```graphql
query GetProduct {
  product(id: "123") {
    # depth 1
    title # depth 2
    brand {
      name # depth 3
    }
  }
}
```

--------------------------------

### Apollo Client Setup for Grafbase

Source: https://grafbase.com/docs/gateway/security/trusted-documents

Configures an Apollo Client instance for Grafbase, integrating `HttpLink` with a specific client name header and `createPersistedQueryLink` for optimized GraphQL requests. This setup is crucial for client-side interaction with a Grafbase API.

```javascript
const httpLink = new HttpLink({
  uri: 'http://localhost:4000/graphql',
  headers: {
    'x-grafbase-client-name': 'ios-app',
  },
})

const persistedQueryLink = createPersistedQueryLink(
  generatePersistedQueryIdsFromManifest({
    loadManifest: () => import('./path/to/persisted-query-manifest.json'),
  }),
)

const client = new ApolloClient({
  cache: new InMemoryCache(),
  link: persistedQueriesLink.concat(httpLink),
})
```

--------------------------------

### Grafbase Platform Documentation Links

Source: https://grafbase.com/docs/gateway/performance/entity-caching

Provides links to key documentation sections for the Grafbase Platform, covering API, Schema Checks, Schema Proposals, Schema Registry, and Self-Hosting.

```APIDOC
Grafbase Platform Documentation:

API:
  - /docs/platform/api

Schema Checks:
  - /docs/platform/schema-checks

Schema Proposals:
  - /docs/platform/schema-proposals

Schema Registry:
  - /docs/platform/schema-registry

Self-Hosting:
  - /docs/platform/self-hosting
```

--------------------------------

### GraphQL Aliases Calculation Example

Source: https://grafbase.com/docs/gateway/security/operation-limits

Provides an example of how aliased fields are counted towards the operation's alias limit. Each instance of an alias contributes to the total count, regardless of the underlying field. This query has 3 aliases.

```graphql
query GetProduct {
  product(id: "123") {
    title: name # alias 1
    something: name # alias 2
    else: name # alias 3
  }
}
```

--------------------------------

### Grafbase Platform API Reference

Source: https://grafbase.com/docs/gateway/security/authorization

Documentation for the Grafbase Platform API, detailing available endpoints, methods, and schemas for interacting with Grafbase services.

```APIDOC
Grafbase Platform API:
  Endpoint: /docs/platform/api

  This section provides comprehensive documentation for the Grafbase Platform API.
  It covers:
  - Schema Checks: Details on how to validate and manage GraphQL schemas.
  - Schema Proposals: Information on proposing and integrating schema changes.
  - Schema Registry: Documentation for managing and versioning GraphQL schemas.
  - Self-Hosting: Guidance on deploying and managing Grafbase in self-hosted environments.

  Specific API methods, parameters, request/response formats, and examples are detailed within the linked documentation.
```

--------------------------------

### Grafbase Federation Documentation Links

Source: https://grafbase.com/docs/gateway/performance/entity-caching

Provides links to key documentation sections for Grafbase Federation, covering overview and directives.

```APIDOC
Grafbase Federation Documentation:

Overview:
  - /docs/federation/overview

Directives:
  - /docs/federation/graphql-directives
```

--------------------------------

### GraphQL Root Fields Calculation Example

Source: https://grafbase.com/docs/gateway/security/operation-limits

Illustrates the calculation of root fields in a GraphQL operation, including those from fragments. Each root field invocation, even if aliased, is counted towards the limit. This example shows 3 root fields.

```graphql
query GetProducts {
  topBooks { # root field 1
    id
  }
  topMovies { # root field 2
    id
  }
  topGames { # root field 3
    id
  }
}
```

--------------------------------

### GraphQL Height Calculation Example

Source: https://grafbase.com/docs/gateway/security/operation-limits

Demonstrates how the height of a GraphQL operation is calculated, counting unique fields and ignoring aliases. This example shows a query where 'id', 'name', and 'title' (aliased to 'name') are counted, resulting in a height of 3.

```graphql
query GetProduct {
  product(id: "123") {
    # height 1
    id # height 2
    name # height 3
    title: name # aliases don't count
  }
}
```

--------------------------------

### Apollo Client Persisted Queries Setup

Source: https://grafbase.com/docs/gateway/security/trusted-documents

Illustrates the client-side setup for Apollo Client to work with Trusted Documents. It involves generating operation manifests, creating a persisted query link, and configuring the client to send document IDs and the `x-grafbase-client-name` header.

```JavaScript
import { ApolloClient, HttpLink, InMemoryCache } from '@apollo/client'
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries'
import { generatePersistedQueryIdsFromManifest } from '@apollo/persisted-query-lists'

// Example setup (requires manifest generation and link configuration)
// const client = new ApolloClient({
//   link: createPersistedQueryLink().concat(new HttpLink({ uri: '/graphql' })) // Simplified example
//   cache: new InMemoryCache(),
// });

// Note: The provided text only shows imports and a partial client instantiation.
// Full implementation requires generating the manifest and configuring the link correctly.
```

--------------------------------

### Grafbase Enterprise Platform Components

Source: https://grafbase.com/docs/platform/self-hosting

Details the core components that make up the Grafbase Enterprise Platform, outlining their roles within the self-hosted solution.

```APIDOC
Grafbase Enterprise Platform Components:

- Grafbase API:
  - Description: The management API of the platform.

- Grafbase Dashboard:
  - Description: Web-based interface to manage graphs and access analytics.

- Telemetry Sink:
  - Description: Collects telemetry data from the Grafbase Gateway and writes it to Kafka.

- Object Storage:
  - Description: A service that sits in front of an S3-compatible bucket to serve schemas and trusted documents with authentication and authorization.
```
Tokens:
Raw