Hive

https://the-guild.dev/graphql/hive/docs/
Admin
Hive is a MIT open-source GraphQL platform for managing, collaborating on, and serving GraphQL...
Tokens:537,484
Snippets:4,607
Trust Score:10
Update:23 hours ago
Show doc for...
Tokens:
Raw
### Install go-gqlhive with go get

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/gqlgen-go

Install the go-gqlhive library using the go get command. This is the first step to enable usage reporting in a gqlgen server.

```bash
go get github.com/enisdenjo/go-gqlhive@v2
```

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

### Install OpenTelemetry SDK packages for context propagation (bun)

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Install the required OpenTelemetry packages for manual setup using bun: @opentelemetry/sdk-node, @opentelemetry/exporter-trace-otlp-grpc, and @opentelemetry/propagator-b3.

```bash
bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-b3
```

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

### Example .env file with comments and multiple variables

Source: https://the-guild.dev/graphql/hive/docs/new-laboratory/environment-variables

A more comprehensive example showing comments, API keys, environment flags, and URLs. Lines starting with # are ignored, as are empty lines.

```plaintext
# API Configuration
API_KEY=sk_live_1234567890
API_SECRET=secret_abc123

# Environment
ENV=production
DEBUG=false

# URLs
BASE_URL=https://api.example.com
GRAPHQL_ENDPOINT=/graphql
```

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

### Example package.json for Cloud Run

Source: https://the-guild.dev/graphql/hive/docs/gateway/deployment/serverless/google-cloud-platform

Example package.json with a start script that runs the Hive Gateway CLI with the supergraph command. This uses ESM syntax and includes the necessary dependencies.

```json
{
  "name": "hive-gateway-cloud-run-guide",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "hive-gateway supergraph"
  },
  "dependencies": {
    "graphql": "latest",
    "@graphql-hive/gateway": "latest"
  }
}
```

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

### Install OpenTelemetry SDK packages for context propagation (npm)

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Install the required OpenTelemetry packages for manual setup using npm: @opentelemetry/sdk-node, @opentelemetry/exporter-trace-otlp-grpc, and @opentelemetry/propagator-b3.

```bash
npm i @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-b3
```

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

### Install OpenTelemetry SDK packages for context propagation (yarn)

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Install the required OpenTelemetry packages for manual setup using yarn: @opentelemetry/sdk-node, @opentelemetry/exporter-trace-otlp-grpc, and @opentelemetry/propagator-b3.

```bash
yarn add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-b3
```

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

### Install OpenTelemetry SDK packages for context propagation (pnpm)

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Install the required OpenTelemetry packages for manual setup using pnpm: @opentelemetry/sdk-node, @opentelemetry/exporter-trace-otlp-grpc, and @opentelemetry/propagator-b3.

```bash
pnpm add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/propagator-b3
```

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

### Install @graphql-hive/core with bun

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/schema-stitching

Alternative installation command using bun.

```bash
bun add @graphql-hive/core
```

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

### Install graphql-ws with bun

Source: https://the-guild.dev/graphql/hive/docs/router/subscriptions/websockets

Install the graphql-ws package using bun.

```bash
bun add graphql-ws
```

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

### Install @escape.tech/graphql-armor-max-aliases with bun

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/security/max-aliases

Install the plugin using bun.

```bash
bun add @escape.tech/graphql-armor-max-aliases
```

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

### Install meros with bun

Source: https://the-guild.dev/graphql/hive/docs/router/subscriptions/incremental-delivery

Install the 'meros' utility using bun.

```bash
bun add meros
```

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

### Install @graphql-mesh/plugin-mock with bun

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/testing/mocking

Install the @graphql-mesh/plugin-mock package using bun.

```bash
bun add @graphql-mesh/plugin-mock
```

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

### Install @graphql-hive/core with yarn

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/schema-stitching

Alternative installation command using yarn.

```bash
yarn add @graphql-hive/core
```

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

### Install @graphql-mesh/plugin-mock with yarn

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/testing/mocking

Install the @graphql-mesh/plugin-mock package using yarn.

```bash
yarn add @graphql-mesh/plugin-mock
```

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

### Install @graphql-mesh/plugin-mock with npm

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/testing/mocking

Install the @graphql-mesh/plugin-mock package using npm.

```bash
npm i @graphql-mesh/plugin-mock
```

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

### Install graphql-ws with yarn

Source: https://the-guild.dev/graphql/hive/docs/router/subscriptions/websockets

Install the graphql-ws package using yarn.

```bash
yarn add graphql-ws
```

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

### Install @graphql-mesh/plugin-mock with pnpm

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/testing/mocking

Install the @graphql-mesh/plugin-mock package using pnpm.

```bash
pnpm add @graphql-mesh/plugin-mock
```

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

### Full example with dedicated listener and heartbeat

Source: https://the-guild.dev/graphql/hive/docs/router/subscriptions/http-callback

Complete example with a dedicated callback server on port 4001, internal public URL, explicit path, heartbeat interval of 5 seconds, and subgraphs list.

```yaml
subscriptions:
  enabled: true
  callback:
    public_url: https://router.internal:4001/callback
    listen: 0.0.0.0:4001
    path: /callback
    heartbeat_interval: 5s
    subgraphs:
      - reviews
      - products
```

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

### Run Hive Gateway Runtime on Bun with Bun.serve

Source: https://the-guild.dev/graphql/hive/docs/gateway/deployment/runtimes/bun

Use this method only if you know what you are doing; the CLI is recommended for most cases. The example creates a gateway runtime and serves it via Bun.serve, logging the server URL.

```javascript
import { createGatewayRuntime } from "@graphql-hive/gateway-runtime";

const gatewayRuntime = createGatewayRuntime(/* Your configuration */);

const server = Bun.serve({
  fetch: gatewayRuntime,
});

console.info(
  `Server is running on ${new URL(
    server.graphqlEndpoint,
    `http://${server.hostname}:${server.port}`,
  )}`,
);
```

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

### Create an App Deployment from a directory

Source: https://the-guild.dev/graphql/hive/docs/schema-registry/app-deployments

Shows alternative ways to provide operations: a directory, a glob pattern, or an existing manifest file. When a directory or glob is used, app:create scans for *.graphql files, normalizes each operation, computes a SHA-256 hash, and builds the manifest. The last example omits --version to auto-generate a random version.

```bash
# from a directory
hive app:create --name my-app --version 1.0.0 ./src/operations

# from a glob pattern
hive app:create --name my-app --version 1.0.0 "./src/**/*.graphql"

# from an existing manifest file
hive app:create --name my-app --version 1.0.0 persisted-operations.json

# with auto-generated version
hive app:create --name my-app persisted-operations.json
```

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

### Get CLI help with --help

Source: https://the-guild.dev/graphql/hive/docs/api-reference/gateway-cli

Run `hive-gateway --help` to display usage information and all available options.

```bash
hive-gateway --help
```

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

### Full coprocessor configuration example

Source: https://the-guild.dev/graphql/hive/docs/router/configuration/coprocessor

Complete example using a Unix socket, h2c protocol, conditions, and include selections for all stages.

```yaml
coprocessor:
  url: unix:///tmp/hive-coprocessor.sock?path=/coprocessor
  protocol: h2c
  timeout: 1s
  stages:
    router:
      request:
        condition:
          expression: .request.method == "POST"
        include:
          headers: true
          method: true
          path: true
          context:
            - hive::operation::name
      response:
        include:
          headers: true
          status_code: true
    graphql:
      request:
        include:
          body: [query, operationName, variables, extensions]
          headers: true
          context: true
      analysis:
        include:
          body: [query]
          context:
            - your.custom_key
      response:
        include:
          body: true
          headers: true
          status_code: true
```

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

### Install dependencies for federation subscriptions example

Source: https://the-guild.dev/graphql/hive/docs/gateway/subscriptions

Install graphql-yoga, @apollo/subgraph, and graphql using your preferred package manager. The commands are equivalent for npm, yarn, pnpm, and bun.

```bash
npm i graphql-yoga @apollo/subgraph graphql
```

```bash
yarn add graphql-yoga @apollo/subgraph graphql
```

```bash
pnpm add graphql-yoga @apollo/subgraph graphql
```

```bash
bun add graphql-yoga @apollo/subgraph graphql
```

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

### Example .env file with environment variables

Source: https://the-guild.dev/graphql/hive/docs/new-laboratory/environment-variables

Shows a .env file format with sample variables for API keys, tokens, and endpoints. Use this as a template for your own environment configuration.

```plaintext
API_KEY=your-api-key-here
AUTH_TOKEN=your-auth-token
ENDPOINT_URL=https://api.example.com/graphql
ENVIRONMENT=development
```

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

### Install with bun

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/opentelemetry

Install the OpenTelemetry plugin and context-async-hooks package using bun.

```bash
bun add @graphql-hive/plugin-opentelemetry @opentelemetry/context-async-hooks
```

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

### Access environment variables in preflight scripts using lab.environment

Source: https://the-guild.dev/graphql/hive/docs/new-laboratory/environment-variables

Use the `lab.environment` API to get, set, and delete environment variables in preflight scripts. The example shows the three methods: `get`, `set`, and `delete`.

```javascript
// Get a variable
const apiKey = lab.environment.get("API_KEY");

// Set a variable
lab.environment.set("API_KEY", "new-value");

// Delete a variable
lab.environment.delete("API_KEY");
```

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

### Read raw query string in on_graphql_parse

Source: https://the-guild.dev/graphql/hive/docs/router/customizations/plugin-system/hooks

Example of reading the raw query string from the start phase payload before parsing.

```rust
async fn on_graphql_parse<'exec>(
    &'exec self,
    payload: OnGraphQLParseStartHookPayload<'exec>,
) -> OnGraphQLParseHookResult<'exec> {
    let raw_query = &payload.graphql_params.query;

    payload.proceed()
}
```

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

### onEnveloped

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/custom-plugins

Hook called once per operation at the start of the GraphQL execution pipeline. Useful for setup before an incoming execution flow.

```APIDOC
## onEnveloped

### Description
Called once per operation, at the start of the GraphQL execution pipeline. Useful for setup before an incoming execution flow.

### Payload Fields
- **setSchema** - Sets the schema to be used.
- **context** - The GraphQL context object.
- **extendContext** - Extends the GraphQL context object with additional fields.

```

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

### Create Hive instance for custom integration

Source: https://the-guild.dev/graphql/hive/docs/api-reference/client

Start a custom integration by creating a Hive instance with createHive. The example enables debug mode and sets a token.

```typescript
import { createHive } from "@graphql-hive/core";

const hive = createHive({
  enabled: true,
  debug: true, // or, false
  token: "YOUR-TOKEN",
});
```

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

### Create and publish in one step

Source: https://the-guild.dev/graphql/hive/docs/schema-registry/app-deployments

Adds the --publish flag to app:create to publish the app deployment immediately after creation, avoiding a separate app:publish command.

```bash
hive app:create \
  --registry.accessToken "<ACCESS_TOKEN>" \
  --target "<ORGANIZATION>/<PROJECT>/<TARGET>" \
  --name "my-app" \
  --version "1.0.0" \
  --publish \
  persisted-documents.json
```

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

### Basic Auth0/Okta Setup - router.config.yaml

Source: https://the-guild.dev/graphql/hive/docs/router/configuration/jwt

Configures JWT authentication with a remote JWKS provider, requiring authentication, setting audiences and issuers. Use this as a starting point for Auth0 or Okta.

```yaml
jwt:
  require_authentication: true
  jwks_providers:
    - source: remote
      url: https://your-domain.auth0.com/.well-known/jwks.json
      polling_interval: "1h"
  audiences:
    - "https://your-api.com"
  issuers:
    - "https://your-domain.auth0.com/"
```

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

### Create a new Rust project

Source: https://the-guild.dev/graphql/hive/docs/router/customizations/plugin-system/usage

Initializes a new Rust binary project named 'my_custom_router' and navigates into it.

```bash
cargo new --bin my_custom_router
cd my_custom_router
```

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

### Wrap execute function with collectUsage

Source: https://the-guild.dev/graphql/hive/docs/api-reference/client

Call collectUsage at operation start and use the returned callback to finish measuring times and save the operation report. The example wraps the execute function.

```typescript
export async function executeWithHive(
  args: ExecutionArgs,
): Promise<ExecutionResult> {
  // args is ExecutionArgs of graphql-js
  const finish = hive.collectUsage(args);
  // result is ExecutionResult of graphql-js
  const result = await execute(args);
  // Use this callback to finish measuring times, and save the operation report
  finish(result);

  return result;
}
```

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

### Install @opentelemetry/resources with bun

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Install the OpenTelemetry resources package using bun.

```bash
bun add @opentelemetry/resources
```

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

### Set up OpenTelemetry for console logging in telemetry.ts

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Use this snippet to set up OpenTelemetry with an AsyncLocalStorageContextManager, which is required for the stdout exporter example. It imports the setup from the plugin package and registers the context manager.

```TypeScript
// For CLI usage
import { openTelemetrySetup } from "@graphql-hive/plugin-opentelemetry/setup";

// For Programmatic usage
import { openTelemetrySetup } from "@graphql-hive/plugin-opentelemetry/setup";
import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";

openTelemetrySetup({
  contextManager: new AsyncLocalStorageContextManager(),
});
```

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

### Add gqlhive tracer to gqlgen server

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/gqlgen-go

After setting up usage reporting in Hive Console and getting started with gqlgen, add the tracer to the server. Replace the placeholders with your target ID and access token.

```go
package main

import (
	"log"
	"net/http"
	"os"

	"github.com/99designs/gqlgen/graphql/handler"
	"github.com/99designs/gqlgen/graphql/handler/transport"
	"github.com/99designs/gqlgen/graphql/playground"
	"github.com/enisdenjo/go-gqlhive"
)

const defaultPort = "8080"

func main() {
	port := os.Getenv("PORT")
	if port == "" {
		port = defaultPort
	}

	srv := handler.New(NewExecutableSchema(graph.Config{Resolvers: &resolvers{}}))
	srv.AddTransport(transport.POST{})

	srv.Use(gqlhive.NewTracer(
		"<TARGET_ID> or <ORGANIZATION>/<PROJECT>/<TARGET>",
		"<ACCESS_TOKEN>",
	))

	http.Handle("/", playground.Handler("GraphQL playground", "/query"))
	http.Handle("/query", srv)

	log.Printf("connect to http://localhost:%s/ for GraphQL playground", port)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}
```

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

### Install Langfuse client with bun

Source: https://the-guild.dev/graphql/hive/docs/gateway/mcp/description-providers

Install the @langfuse/client package using bun.

```bash
bun add @langfuse/client
```

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

### Capture operation for usage reporting with operation_for_plan

Source: https://the-guild.dev/graphql/hive/docs/router/customizations/plugin-system/hooks

Read operation_for_plan in the start phase to record the query string and operation name for telemetry or analytics before execution proceeds. The example pushes a UsageReport to a reports collection.

```rust
async fn on_execute<'exec>(
    &'exec self,
    payload: OnExecuteStartHookPayload<'exec>,
) -> OnExecuteStartHookResult<'exec> {
    self.reports.lock().await.push(UsageReport {
        query: payload.operation_for_plan.to_string(),
        operation_name: payload.operation_for_plan.name.clone(),
    });

    payload.proceed()
}
```

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

### Install @graphql-hive/gateway-runtime with bun

Source: https://the-guild.dev/graphql/hive/docs/gateway/deployment

Install the Hive Gateway runtime package using bun.

```bash
bun add @graphql-hive/gateway-runtime
```

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

### Production baseline OTLP exporter configuration

Source: https://the-guild.dev/graphql/hive/docs/router/observability/metrics

Defines a minimal production telemetry setup with a single OTLP exporter, a service identity, and default instrumentation. Use this as a safe starting point before adding more exporters or customizing instrumentation.

```yaml
telemetry:
  resource:
    attributes:
      service.name: hive-router
      service.namespace: your-platform
      deployment.environment:
        expression: env("ENVIRONMENT")
  metrics:
    exporters:
      - kind: otlp
        enabled: true
        protocol: grpc
        endpoint: https://otel-collector.example.com:4317
        interval: 30s
        max_export_timeout: 5s
```

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

### Quick start with createGatewayTester

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/testing/gateway-tester

Example test file (gateway.spec.ts) showing how to create a gateway tester with an inline subgraph, execute a query, and verify a plugin's onFetch hook is called. Uses await using for proper disposal.

```typescript
import { expect, vi } from "vitest";
import { createGatewayTester } from "@graphql-hive/gateway-testing";

const onFetchFn = vi.fn();

const books = {
  name: "books",
  schema: {
    typeDefs: /* GraphQL */ `
      type Query {
        book(id: ID!): Book
      }

      type Book {
        id: ID!
        title: String!
      }
    `,
    resolvers: {
      Query: {
        book: (_, { id }) => ({ id, title: "The Hive Handbook" }),
      },
    },
  },
};

await using gateway = createGatewayTester({
  subgraphs: [books],
  plugins: () => [
    {
      onFetch({ executionRequest }) {
        onFetchFn(executionRequest?.operationName);
      },
    },
  ],
});

await expect(
  gateway.execute({
    query: /* GraphQL */ `
      query Test {
        book(id: "1") {
          title
        }
      }
    `,
  }),
).resolves.toStrictEqual({
  data: {
    book: {
      title: "The Hive Handbook",
    },
  },
});

expect(onFetchFn).toHaveBeenCalledWith("Test");
```

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

### Configure NodeSDK with OTLP Trace Exporter in telemetry.ts

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Programmatic setup of the OpenTelemetry Node SDK with an OTLP HTTP trace exporter. All configuration is optional; traces are batched by default. The example references getNodeAutoInstrumentations() and getResourceDetectors() which are not defined in the snippet.

```typescript
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { NodeSDK, resources, tracing } from "@opentelemetry/sdk-node";

new NodeSDK({
  // All configuration is optional. OTEL rely on env variables or sensible default value.

  // Defines the exporter, HTTP OTLP most of the time. Traces are batched by default
  traceExporter: new OTLPTraceExporter({ url: "http://<otlp-endpoint>:4317" }),

  // Optional, enables automatic instrumentation, adding traces like network spans.
  instrumentations: getNodeAutoInstrumentations(),

  // Optional, enables automatic resource attributes detection
  resourceDetectors: getResourceDetectors(),
}).start();
```

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

### Install with pnpm

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/opentelemetry

Install the OpenTelemetry plugin and context-async-hooks package using pnpm.

```bash
pnpm add @graphql-hive/plugin-opentelemetry @opentelemetry/context-async-hooks
```

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

### Install with yarn

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/opentelemetry

Install the OpenTelemetry plugin and context-async-hooks package using yarn.

```bash
yarn add @graphql-hive/plugin-opentelemetry @opentelemetry/context-async-hooks
```

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

### Install graphql-hive gem

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/graphql-ruby

Install the graphql-hive gem using the gem install command.

```bash
gem install graphql-hive
```

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

### Install OpenTelemetry SDK and OTLP HTTP Exporter with bun

Source: https://the-guild.dev/graphql/hive/docs/gateway/monitoring-tracing

Install the official OpenTelemetry Node SDK and the OTLP HTTP trace exporter using bun.

```bash
bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
```

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

### Install @graphql-inspector/cli with yarn

Source: https://the-guild.dev/graphql/hive/docs/gateway/other-features/security/audit-documents

Install the @graphql-inspector/cli package using yarn. This is an alternative to npm for installing the CLI.

```bash
yarn add @graphql-inspector/cli
```

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

### Install @graphql-hive/envelop with npm

Source: https://the-guild.dev/graphql/hive/docs/other-integrations/envelop

Install the @graphql-hive/envelop package using npm. It is recommended to install the Hive Client package as a direct dependency.

```bash
npm i @graphql-hive/envelop
```

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

### Install Hive CLI binary on MacOS/Linux

Source: https://the-guild.dev/graphql/hive/docs/api-reference/cli

Downloads and installs the prebuilt Hive CLI binary using the official install script.

```bash
curl -sSL https://graphql-hive.com/install.sh | sh
```

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

### Full cache configuration example

Source: https://the-guild.dev/graphql/hive/docs/router/configuration/cache

Example configuration showing all cache settings under `cache.router` and `cache.supergraph`. Use this as a template for configuring parsing, validation, normalization, and query plan caches.

```yaml
cache:
  router:
    plugin_supergraph_runtimes: 10
    parsing:
      max_entries: 1000
      time_to_live: 30m
      time_to_idle: 5m
  supergraph:
    validation:
      max_entries: 1000
      time_to_idle: 5m
    normalization:
      max_entries: 1000
      time_to_idle: 5m
    query_plans:
      max_entries: 1000
      time_to_idle: 5m
```

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

### Install specific Hive Gateway version

Source: https://the-guild.dev/graphql/hive/docs/schema-registry/get-started/apollo-federation

Installs a specific Hive Gateway version by passing a valid release version (e.g., X.Y.Z) to the install script.

```bash
curl -sSL https://graphql-hive.com/install-gateway.sh | sh -s -- X.Y.Z
```
Tokens:
Raw