Endpoints

An endpoint is the generated, typed surface for a single table. It is a query field (and optionally a mutation field) in the GraphQL schema, backed by a config, an interface, and a validated schema. You get there one of two ways. Both produce the same per-table file set and format, but not to the same place, and not fully interchangeably.

Two paths, same file set, different directories #

pull introspects a live table through its data source. It reads the columns, types, and nullability from the query engine and derives the field definitions for you. It's the fastest path when the data source is reachable at generation time.

create-endpoint --from-file <definition.json> generates from a hand-written or committed JSON definition instead. Use it when you can't reach the data source at generation time, when you want an endpoint for data that isn't introspectable in the usual way, or when you want to keep the definition under version control and regenerate deterministically.

Every table pull generates also writes an endpoint.json alongside its other files, using the same format create-endpoint --from-file consumes. That doesn't make the two paths interchangeable without care. pull does not serialize the dataSource it used into endpoint.json, so recreating a pulled endpoint later with create-endpoint --from-file needs the dataSource field added back by hand. Without it, generation falls back to the default data source. The pages in this section document that endpoint.json format.

What gets generated #

Both commands write the same set of files per table, under your configured source path. pull organizes them by data source, catalog, and schema (schemas/generated/<dataSource>/<catalog>/<schema>/<table>/). create-endpoint writes to a data-source-independent path instead (schemas/custom/<catalog>/<schema>/<table>/):

mutation-schema.ts is written only when the definition includes a mutation block. Its presence is what makes the endpoint register a Mutation root field alongside the query field. See Key Concepts for how these files fit into the rest of the generated layout.

In this section #

• Definition Format — the top-level shape of endpoint.json .
• Field Types — the six primitive types and field-level options.
• Nested Fields — Object and Array field types.
• Mutations — the optional mutation block and load strategies.