Introduction

@lakeql/api is the runtime GraphQL server package in the LakeQL ecosystem. It exposes a fully typed GraphQL API that queries data from Trino — a distributed SQL query engine — and returns structured, paginated results to clients.

The package combines three core libraries into a cohesive server stack:

• Hono — A lightweight, high-performance HTTP framework that handles routing, CORS, and middleware.
• GraphQL Yoga — A spec-compliant GraphQL server with built-in support for subscriptions, file uploads, and health checks.
• Pothos — A code-first, type-safe GraphQL schema builder that generates the schema from TypeScript definitions.

How it connects #

@lakeql/api sits at the center of the LakeQL architecture. It depends on several sibling packages:

Schema loading #

Query and mutation schemas are loaded automatically at startup using glob patterns. The server scans for files matching schemas/**/{query,mutation}-schema.{ts,js,mjs} in the configured schema directory. Each schema file registers its types and resolvers on the shared Pothos builder — no manual wiring required.

Quick start #

Install the required packages:

npm install @lakeql/api @lakeql/query-builder @lakeql/trino-client @t3-oss/env-core zod

Set up the configuration (src/config.ts):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { defineConfig } from "@lakeql/api/config"

import { getUser } from "./auth"
import { allConfigs } from "./config-registry"
import { permissions } from "./permissions"

const baseDir = import.meta.dirname

export const config = defineConfig({
  allConfigs,
  baseDir,
  getUser,
  graphqlPath: "/graphql",
  healthCheckEndpoint: "/live",
  permissions,
  port: 4000,
  schemaPath: "./schemas",
})

Create the entry point (src/index.ts):

1
2
3
4
import { config } from "./config"

await config.startServer()

The server starts on http://localhost:4000 with GraphiQL available at /graphql in development mode.