create-endpoint #

Generate a custom endpoint (query + mutation) from a JSON definition file. The definition file can be created using the Endpoint Builder UI or written by hand.

Generated files #

Files are written to schemas/custom/<catalog>/<schema>/<tableName>/:

config.ts — Endpoint configuration
interface.ts — TypeScript interface for the endpoint fields
query-schema.ts — GraphQL query schema definition
mutation-schema.ts — GraphQL mutation schema with write pipeline resolver (only when mutation is configured)
validations.ts — Zod validation schema (only when fields have validations configured)
json-schema.json — JSON Schema representation
endpoint.json — The endpoint definition (for re-generation)

The mutation-schema.ts and validations.ts files are only generated when the endpoint definition includes mutation configuration. Query-only endpoints skip these files entirely.

Usage #

1
2
lakeql-cli create-endpoint --from-file ./my-endpoint.json

With mutation enabled #

1
2
3
4
5
6
7
8
9
10
11
✔ Loaded definition: user_events (catalog: hive, schema: analytics)
  → schemas/custom/hive/analytics/user_events/config.ts
  → schemas/custom/hive/analytics/user_events/interface.ts
  → schemas/custom/hive/analytics/user_events/query-schema.ts
  → schemas/custom/hive/analytics/user_events/mutation-schema.ts
  → schemas/custom/hive/analytics/user_events/validations.ts
  → schemas/custom/hive/analytics/user_events/json-schema.json
  → schemas/custom/hive/analytics/user_events/endpoint.json
  Load strategy: full_load
✔ Config registry updated

Without mutation (query-only) #

1
2
3
4
5
6
7
8
9
✔ Loaded definition: my_table (catalog: analytics, schema: tracking)
  → schemas/custom/analytics/tracking/my_table/config.ts
  → schemas/custom/analytics/tracking/my_table/interface.ts
  → schemas/custom/analytics/tracking/my_table/query-schema.ts
  → schemas/custom/analytics/tracking/my_table/json-schema.json
  → schemas/custom/analytics/tracking/my_table/endpoint.json
  mutation: disabled
✔ Config registry updated

Definition file format #

The JSON definition file must conform to the EndpointDefinitionFormat schema:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47{
  "version": "1.0",
  "tableName": "user_events",
  "catalog": "hive",
  "schema": "analytics",
  "fields": [
    {
      "name": "email",
      "type": "String",
      "options": {
        "required": true,
        "validations": [{ "type": "email" }]
      }
    },
    {
      "name": "age",
      "type": "Integer",
      "options": {
        "required": false,
        "validations": [
          { "type": "min", "value": 0 },
          { "type": "max", "value": 150 }
        ]
      }
    },
    { "name": "event_id", "type": "String" },
    { "name": "timestamp", "type": "DateTime" },
    {
      "name": "metadata",
      "type": "Object",
      "fields": [{ "name": "source", "type": "String" }]
    },
    {
      "name": "tags",
      "type": "Array",
      "items": { "type": "String" }
    }
  ],
  "mutation": {
    "loadStrategy": "full_load",
    "type": "s3",
    "bucket": "my-datalake",
    "basePath": "warehouse/analytics/user_events",
    "endpoint": "https://s3.eu-central-1.amazonaws.com"
  }
}

Supported field types #

Primitives: String, Integer, Float, Boolean, Date, DateTime
Object: Nested object with child fields (max 5 levels)
Array: Array of primitives or objects

The optional mutation field controls whether a write pipeline is generated for this endpoint. Set it to false (or omit it) for query-only endpoints. Set it to a configuration object to enable the mutation pipeline.

Property	Type
loadStrategy	`LoadStrategy`
Load strategy for the write pipeline.
type	`StorageType`
Storage adapter type. Default: `"s3"`
bucket	`string`
S3/MinIO bucket name for endpoint data.
basePath	`string`
Base path for endpoint data.
region?	`string`
Optional region override (falls back to AWS_DEFAULT_REGION env var for S3).
endpoint?	`string`
Optional custom endpoint. Required for MinIO, optional for S3.
partitioning?	`PartitioningValue`
Partitioning mode. `true` partitions by write timestamp, `false` disables partitioning, or a string for field-based/custom partitioning. Default: `true`
partitioningFormat?	`string`
Partition path granularity. One of `"year"`, `"year/month"`, or `"year/month/day"`. Default: `"year/month/day"`

The type field defaults to "s3". Use "minio" for local development with a MinIO-compatible endpoint. See the Mutations guide for environment variable details.

Mutation with partitioning options #

1
2
3
4
5
6
7
8
9
10
11
{
  "mutation": {
    "loadStrategy": "append",
    "type": "s3",
    "bucket": "my-datalake",
    "basePath": "warehouse/raw/events",
    "partitioning": "event_date",
    "partitioningFormat": "year/month"
  }
}

The partitioning and partitioningFormat fields are omitted from generated configs when loadStrategy is full_load. See the Mutations guide for full details on each partitioning mode.

See the Load Strategies guide for details on when to use each strategy.

Endpoints generated via the pull command always set mutation: false since pulled tables are query-only by default.

Field options #

Each field can include an optional options object to control mutation input behavior:

Property	Type
required?	`boolean`
Whether the field is required in mutation input. Default: `false`
validations?	`FieldValidation[]`
Validation refinements to apply via Zod at runtime. Default: `[]`
readOnly?	`boolean`
Whether the field is read-only. Read-only fields appear in the query schema and Hive DDL but are excluded from the mutation input type. Default: `false`

When timestamp-based partitioning is active, the Endpoint Builder automatically adds load_timestamp (DateTime), load_timestamp_year (Integer), and load_timestamp_month (Integer) fields with readOnly: true. These fields are populated by the write pipeline at runtime and are queryable in Hive and directly in Parquet, but users cannot provide them as mutation input.

Available validations #

Validation	Applies to	Description	Example
`email`	String	Must be a valid email address	`{ "type": "email" }`
`url`	String	Must be a valid URL	`{ "type": "url" }`
`uuid`	String	Must be a valid UUID	`{ "type": "uuid" }`
`min`	Integer, Float	Minimum numeric value	`{ "type": "min", "value": 0 }`
`max`	Integer, Float	Maximum numeric value	`{ "type": "max", "value": 150 }`
`regex`	String	Must match a regular expression	`{ "type": "regex", "pattern": "^[A-Z]" }`

Validation rules #

tableName , catalog , schema : alphanumeric + underscore, no leading digit, max 128 chars
Field names: alphanumeric + underscore, no leading digit, max 64 chars
No duplicate field names at the same nesting level
Object fields must have at least 1 child field

Workflow #

Use the Endpoint Builder to define your schema visually
Configure mutation support and load strategy if write operations are needed
Download the JSON definition file
Run lakeql-cli create-endpoint --from-file ./your-endpoint.json
The generated mutation resolver is fully wired to the write pipeline — no manual stub implementation needed

Options #

--from-file <path>

Path to a JSON definition file conforming to the Endpoint_Definition_Format

Property	Value
Type	`string`
Required	Yes

--source-path <path>

Base path for generated code (resolved from the command invocation directory). Files are created in `schemas/generated|custom` inside this path.

Property	Value
Type	`string`
Required	No
Default	`command invocation directory`

--skip-registry

Skip config registry generation

Property	Value
Type	`boolean`
Required	No
Default	`false`

--force

Overwrite existing files without prompting

Property	Value
Type	`boolean`
Required	No
Default	`false`