Generic SDL transcription

Prefix: graphql_.

A complete transcription of the GraphQL schema documents, as any SDL reader would see them. Every type, field, argument and directive application lands here exactly as written, with no judgment about what any of it means. The two judgment rows it does hold are the SDL toolchain’s own verdicts on whether the documents parse and validate at all.

Where to start

graphql_type_coordinate: A type name exists in this graph: the anchor every SDL fact, every directive decode and every type-keyed derivation hangs off.
graphql_field: What a field at a coordinate is: its type expression, its description, its default and the site that contributed it, hanging off graphql_field_coordinate.
graphql_directive_site: The one view the DDL ships: every application regardless of site, so a consumer that wants "all applications of @x" reads one relation.

How this family meets the others

The normalization crossings declared for this family: rules by which a name written in one family’s vocabulary is matched against another’s census. Declared rows rather than a closed set, so a crossing nobody has declared does not appear here.

Declared crossings

intent_column_match_claim (graphql_ spellings against the sql_ census): A field’s own name meets the columns of the table its site navigates to, case-insensitively, with no directive involved.

Declared key edges

store_: 7 foreign keys from this family’s rows into that one.
graphitron_: 49 foreign keys from that family’s rows into this one.
intent_: 4 foreign keys from that family’s rows into this one.

Why the name is right

Generic GraphQL: a row any SDL reader could produce from the document without knowing graphitron exists, which is every declaration, every directive definition, and every directive application including graphitron’s own. The family is a total transcription, with no hole where graphitron’s namespace was: whether an application survives into the emitted schema is a namespace query over graphql_directive at emission time, not something capture decides by choosing a table, and a directive that is both re-emitted and decoded (federation’s @key) is simply a row in each family rather than a special case. Two residents are verdicts rather than declarations (graphql_syntax_error, graphql_schema_error: what the SDL toolchain concluded about whether the document is a schema at all), which makes this the one family holding both a transcription and a judgement of the same artifact. They are here on the reader-neutrality test that names the family, since a syntax error and a specification violation are as much things any SDL reader produces from the document as a declaration is, and the alternative was a second family aliasing this one’s subject.

graphql_argument

What an argument on a field is, hanging off graphql_argument_coordinate. Net-new coordinate: today arguments are classified per-field and mostly projected away, with no location kept. Nothing references this relation, on graphql_type’s terms.

Primary key: (graph_name, type_name, field_name, argument_name). Foreign key: (graph_name, type_name, field_name, argument_name) references graphql_argument_coordinate (graph_name, type_name, field_name, argument_name). Check: "IS_LIST" OR ("ITEM_NON_NULL" IS NULL).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): owning type of the field the argument sits on
field_name (CHARACTER VARYING, not null): the field name within the owning type
argument_name (CHARACTER VARYING, not null): the argument name within the owning field
ordinal (INTEGER, not null): declaration order within the field
type_sdl (CHARACTER VARYING, not null): rendered type expression, as on graphql_field
named_type (CHARACTER VARYING, not null): the named type the expression bottoms out in; author-spelled, no FK
non_null (BOOLEAN, not null): outermost non-null wrapper present
is_list (BOOLEAN, not null): a list wrapper is present
item_non_null (BOOLEAN, nullable): item-level non-null when is_list; NULL otherwise
default_value_sdl (CHARACTER VARYING, nullable): rendered default value, when declared
description (CHARACTER VARYING, nullable): SDL description string, when the author wrote one
source_name (CHARACTER VARYING, nullable): the SDL file the row was captured from
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention
argument_name_upper (CHARACTER VARYING, nullable): the upper-cased form of the column beside it, for the case-insensitive match against sql_column’s column_name_upper and jooq_name_upper where @field(name:) was omitted and the argument name stands in as a column spelling. Generated, so nothing writes it and nothing can. The argument-site counterpart of graphql_field.field_name_upper, folded for the same one crossing and for no other: nothing compares one argument name to another case-insensitively

graphql_argument_coordinate

An argument coordinate exists on a field: the anchor for the argument-keyed decode relations, on graphql_type_coordinate’s terms and for its reason.

Primary key: (graph_name, type_name, field_name, argument_name). Foreign key: (graph_name, type_name, field_name) references graphql_field_coordinate (graph_name, type_name, field_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): owning type of the field the argument sits on
field_name (CHARACTER VARYING, not null): the field the argument sits on, anchored by graphql_field_coordinate
argument_name (CHARACTER VARYING, not null): the argument name within the owning field

graphql_argument_directive

A directive is applied to a field argument (ARGUMENT_DEFINITION site).

Primary key: (graph_name, type_name, field_name, argument_name, directive_name, ordinal). Foreign key: (graph_name, type_name, field_name, argument_name) references graphql_argument_coordinate (graph_name, type_name, field_name, argument_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
field_name (CHARACTER VARYING, not null): the field name within the owning type
argument_name (CHARACTER VARYING, not null): the SDL argument the directive sits on
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): as on graphql_field_directive
source_name (CHARACTER VARYING, nullable): the SDL file the row was captured from
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_argument_directive_arg

An argument the author passed to an argument-level application.

Primary key: (graph_name, type_name, field_name, argument_name, directive_name, ordinal, directive_argument_name). Foreign key: (graph_name, type_name, field_name, argument_name, directive_name, ordinal) references graphql_argument_directive (graph_name, type_name, field_name, argument_name, directive_name, ordinal).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
field_name (CHARACTER VARYING, not null): the field name within the owning type
argument_name (CHARACTER VARYING, not null): the argument name within the owning field
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): the owning application’s ordinal
directive_argument_name (CHARACTER VARYING, not null): the definition’s formal argument this value binds
value_sdl (CHARACTER VARYING, not null): the value as written, rendered from the AST

graphql_directive

A directive is defined.

Primary key: (graph_name, directive_name). Foreign key: (graph_name) references store_graph (graph_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
repeatable (BOOLEAN, not null): whether the definition says 'repeatable'; governs the ordinal on applications
description (CHARACTER VARYING, nullable): SDL description string, when the author wrote one
source_name (CHARACTER VARYING, nullable): the SDL file the row was captured from
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_directive_argument

A directive definition declares a formal argument. Carries the same wrapping decode as graphql_field, so list-ness of a directive argument is a column read, not a string parse.

Primary key: (graph_name, directive_name, argument_name). Foreign key: (graph_name, directive_name) references graphql_directive (graph_name, directive_name). Check: "IS_LIST" OR ("ITEM_NON_NULL" IS NULL).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
argument_name (CHARACTER VARYING, not null): the argument name within the owning field
ordinal (INTEGER, not null): declaration order in the definition
type_sdl (CHARACTER VARYING, not null): rendered argument type, e.g. '[ReferenceElement!]!'
named_type (CHARACTER VARYING, not null): the named type the expression bottoms out in; author-spelled, no FK
non_null (BOOLEAN, not null): outermost non-null wrapper present
is_list (BOOLEAN, not null): a list wrapper is present
item_non_null (BOOLEAN, nullable): item-level non-null when is_list; NULL otherwise
default_value_sdl (CHARACTER VARYING, nullable): rendered default; the value an application inherits when it omits the argument
description (CHARACTER VARYING, nullable): SDL description string, when the author wrote one
source_name (CHARACTER VARYING, nullable): position of the formal argument in the definition
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_directive_location

A directive definition names a permitted location.

Primary key: (graph_name, directive_name, location). Foreign key: (graph_name, directive_name) references graphql_directive (graph_name, directive_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
location (CHARACTER VARYING, not null): introspection location name, e.g. FIELD_DEFINITION, INPUT_FIELD_DEFINITION

graphql_directive_site (view)

The one view the DDL ships: every application regardless of site, so a consumer that wants "all applications of @x" reads one relation.

Columns

graph_name (CHARACTER VARYING, nullable): the owning graph’s partition, carried through from every arm’s base relation
site_kind (CHARACTER VARYING, nullable): which element family the application sits on; the arm this row came from
type_name (CHARACTER VARYING, nullable): the owning type, NULL on the schema-level arm
member_name (CHARACTER VARYING, nullable): the field or enum value the application sits on, NULL where the site has none
argument_name (CHARACTER VARYING, nullable): the field argument the application sits on, NULL where the site has none
directive_name (CHARACTER VARYING, nullable): the applied directive name, without the leading @
ordinal (INTEGER, nullable): 0 unless the directive is repeatable; repeats number in document order
source_name (CHARACTER VARYING, nullable): the SDL file the application was captured from
source_line (INTEGER, nullable): source line of the application, 1-based
source_column (INTEGER, nullable): source column of the application, 1-based

graphql_duplicate_declaration

The duplicate-declaration overflow, sibling of graphitron_undecoded_argument in that each is its family’s overflow relation, holding what that family’s primary write path declined. The registry retains element-level duplicates without error (a field declared twice in one body or re-declared by an extension, a repeated argument, enum value, union member, or implements entry, a second application of a single-application graphitron directive, a repeated location or formal argument in a directive definition), so every element-level natural key in this schema is author-reachable. Capture is first-wins in merge order; the losing occurrence records here, rendered and located, so no authored text is lost and the duplicate-declaration detection has its row. The element-level kinds became reachable when capture stopped being conditional on the document assembling: assembly does reject these schemas (a twice-declared field is a NonUniqueNameError), but its refusal is now a row in graphql_schema_error rather than an abort, so the same pass captures both the verdict and the retained duplicate this relation holds. A second base definition, of a type or of a directive, is refused one stage earlier, by the registry, whose first-wins admission keeps the winner and reports the loser as a verdict without offering its declaration to capture; the TYPE kind is therefore still reachable only through the LSP’s per-file fragment path, now because the losing declaration never reaches the walk rather than because the registry throws.

Primary key: (graph_name, source_name, source_line, source_column). Foreign key: (graph_name) references store_graph (graph_name). Check: "ELEMENT_KIND" IN('TYPE', 'FIELD', 'ARGUMENT', 'ENUM_VALUE', 'UNION_MEMBER', 'IMPLEMENTS', 'DIRECTIVE_APPLICATION', 'DIRECTIVE_LOCATION', 'DIRECTIVE_ARGUMENT').

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
source_name (CHARACTER VARYING, not null): the losing occurrence’s own position identifies the row
source_line (INTEGER, not null): line of the losing occurrence
source_column (INTEGER, not null): column of the losing occurrence
element_kind (CHARACTER VARYING, not null): which family’s natural key collided
coordinate (CHARACTER VARYING, not null): the colliding key, rendered (e.g. 'Q.title')
value_sdl (CHARACTER VARYING, not null): the losing occurrence as written, rendered from the AST; children ride inside it, so a losing field keeps its arguments

graphql_enum_value

What a value an enum declares is, hanging off graphql_enum_value_coordinate. Net-new coordinate; deprecation is not a column because @deprecated is an ordinary applied directive. Nothing references this relation, on graphql_type’s terms.

Primary key: (graph_name, type_name, value_name). Foreign key: (graph_name, type_name, value_name) references graphql_enum_value_coordinate (graph_name, type_name, value_name). Foreign key: (graph_name, type_name, source_name, declaration_line, declaration_column) references graphql_type_declaration (graph_name, type_name, source_name, source_line, source_column).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the owning ENUM type
value_name (CHARACTER VARYING, not null): the enum value name within the owning enum type
ordinal (INTEGER, not null): order in the effective enum: base declaration, then extensions
declaration_line (INTEGER, not null): the contributing site, as on graphql_field
declaration_column (INTEGER, not null): column of the contributing declaration site, the site key’s fourth part
description (CHARACTER VARYING, nullable): SDL description string, when the author wrote one
source_name (CHARACTER VARYING, not null): NOT NULL for the same reason as on graphql_field: half of the site FK
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_enum_value_coordinate

An enum value coordinate exists on a type: the anchor for the value-keyed decode relations, on graphql_type_coordinate’s terms and for its reason.

Primary key: (graph_name, type_name, value_name). Foreign key: (graph_name, type_name) references graphql_type_coordinate (graph_name, type_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the owning ENUM type, anchored by graphql_type_coordinate
value_name (CHARACTER VARYING, not null): the enum value name within the owning enum type

graphql_enum_value_directive

A directive is applied to an enum value (@deprecated lives here, and so does the graphitron enum-value inventory, which is additionally decoded).

Primary key: (graph_name, type_name, value_name, directive_name, ordinal). Foreign key: (graph_name, type_name, value_name) references graphql_enum_value_coordinate (graph_name, type_name, value_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
value_name (CHARACTER VARYING, not null): the enum value name within the owning enum type
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): as on graphql_schema_directive
source_name (CHARACTER VARYING, nullable): the SDL file the row was captured from
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_enum_value_directive_arg

An argument the author passed to an enum-value application.

Primary key: (graph_name, type_name, value_name, directive_name, ordinal, directive_argument_name). Foreign key: (graph_name, type_name, value_name, directive_name, ordinal) references graphql_enum_value_directive (graph_name, type_name, value_name, directive_name, ordinal).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
value_name (CHARACTER VARYING, not null): the enum value name within the owning enum type
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): the owning application’s ordinal
directive_argument_name (CHARACTER VARYING, not null): the definition’s formal argument this value binds
value_sdl (CHARACTER VARYING, not null): the value as written, rendered from the AST

graphql_field

What a field at a coordinate is: its type expression, its description, its default and the site that contributed it, hanging off graphql_field_coordinate. OBJECT and INTERFACE parents make it an output field, INPUT_OBJECT parents an input field; the join decides. Nothing references this relation, on graphql_type’s terms: the field-keyed reference web anchors on the coordinate instead.

Primary key: (graph_name, type_name, field_name). Foreign key: (graph_name, type_name, field_name) references graphql_field_coordinate (graph_name, type_name, field_name). Foreign key: (graph_name, type_name, source_name, declaration_line, declaration_column) references graphql_type_declaration (graph_name, type_name, source_name, source_line, source_column). Check: "IS_LIST" OR ("ITEM_NON_NULL" IS NULL).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): owning type
field_name (CHARACTER VARYING, not null): the field name within the owning type
ordinal (INTEGER, not null): order in the effective type: base declaration, then extensions in document order (capture merges them from the registry)
declaration_line (INTEGER, not null): the contributing declaration site, keyed with this row’s own source_name (an authored row sits lexically inside its site; a synthesized row shares its synthesized site’s inherited position)
declaration_column (INTEGER, not null): the site key’s fourth part, as on graphql_type_declaration
type_sdl (CHARACTER VARYING, not null): the rendered type expression, e.g. '[Film!]!'; authoritative for wrapping fidelity
named_type (CHARACTER VARYING, not null): the named type the expression bottoms out in; author-spelled, no FK, integrity is a detection
non_null (BOOLEAN, not null): outermost non-null wrapper present
is_list (BOOLEAN, not null): a list wrapper is present
item_non_null (BOOLEAN, nullable): item-level non-null when is_list; NULL otherwise
default_value_sdl (CHARACTER VARYING, nullable): rendered default value; input-object fields only
description (CHARACTER VARYING, nullable): SDL description string, when the author wrote one
source_name (CHARACTER VARYING, not null): every field row comes from an SDL site (built-in scalars declare none), and a NULL here would silently disable the site FK under MATCH SIMPLE
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention
field_name_upper (CHARACTER VARYING, nullable): the upper-cased form of the column beside it, for the case-insensitive match against sql_column’s column_name_upper and jooq_name_upper where @field(name:) was omitted and the field name stands in as a column spelling. Generated, so nothing writes it and nothing can. A GraphQL field name is folded here for that crossing alone; nothing compares one to another case-insensitively

graphql_field_coordinate

A field coordinate exists on a type: the anchor for the field-keyed half of the reference web, on graphql_type_coordinate’s terms and for its reason. Written from the declaration sites, so the coordinate exists as soon as one site declares the field, and a coordinate two sites declare is one row (the losing declaration is the duplicate quarantine’s business, not this relation’s). OBJECT and INTERFACE parents make it an output field, INPUT_OBJECT parents an input field; the join to the parent’s kind decides, and this relation asserts neither.

Primary key: (graph_name, type_name, field_name). Foreign key: (graph_name, type_name) references graphql_type_coordinate (graph_name, type_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the owning type, anchored by graphql_type_coordinate
field_name (CHARACTER VARYING, not null): the field name within the owning type

graphql_field_directive

A directive is applied to a field (output or input-object; the parent type’s kind decides which SDL location this was).

Primary key: (graph_name, type_name, field_name, directive_name, ordinal). Foreign key: (graph_name, type_name, field_name) references graphql_field_coordinate (graph_name, type_name, field_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
field_name (CHARACTER VARYING, not null): the field name within the owning type
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): 0 unless the directive is repeatable; repeats number in document order
source_name (CHARACTER VARYING, nullable): the SDL file the row was captured from
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_field_directive_arg

An argument the author passed to a field-level application.

Primary key: (graph_name, type_name, field_name, directive_name, ordinal, directive_argument_name). Foreign key: (graph_name, type_name, field_name, directive_name, ordinal) references graphql_field_directive (graph_name, type_name, field_name, directive_name, ordinal).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
field_name (CHARACTER VARYING, not null): the field name within the owning type
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): the owning application’s ordinal
directive_argument_name (CHARACTER VARYING, not null): the definition’s formal argument this value binds
value_sdl (CHARACTER VARYING, not null): the value as written, rendered from the AST

graphql_implements

A type declares that it implements an interface. Stored in declaration direction; today’s model keeps only the inverted interface-to-participants list and reads this edge live off graphql-java.

Primary key: (graph_name, type_name, interface_name). Foreign key: (graph_name, type_name) references graphql_type_coordinate (graph_name, type_name). Foreign key: (graph_name, type_name, source_name, declaration_line, declaration_column) references graphql_type_declaration (graph_name, type_name, source_name, source_line, source_column).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the implementing OBJECT or INTERFACE
interface_name (CHARACTER VARYING, not null): the interface as the implementing type spelled it; author-spelled, no FK
declaration_line (INTEGER, not null): the contributing site, as on graphql_field
declaration_column (INTEGER, not null): column of the contributing declaration site, the site key’s fourth part
source_name (CHARACTER VARYING, not null): position of the interface token itself; NOT NULL as on graphql_field
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_root_operation

The schema definition names a root operation type. These rows are the seeds the reachability derivation grows from. The binding is an author-spelled reference, so its dangling case mints a located diagnostic; the position columns are what it locates from. (A double binding cannot reach capture: a schema extension re-binding an operation throws at parse.)

Primary key: (graph_name, operation). Foreign key: (graph_name) references store_graph (graph_name). Check: "OPERATION" IN('QUERY', 'MUTATION', 'SUBSCRIPTION').

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
operation (CHARACTER VARYING, not null): which root slot
type_name (CHARACTER VARYING, not null): the object type serving it
source_name (CHARACTER VARYING, nullable): position of the binding inside the schema { } block; all three NULL exactly when the binding is the name-convention default no SDL line spells
source_line (INTEGER, nullable): line of the binding; NULL with the siblings when the binding is the name-convention default
source_column (INTEGER, nullable): column of the binding; NULL with the siblings when the binding is the name-convention default

graphql_schema_directive

A directive is applied to the schema definition (@link lives here).

Primary key: (graph_name, directive_name, ordinal). Foreign key: (graph_name) references store_graph (graph_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): 0 unless the directive is repeatable; repeats number in document order
source_name (CHARACTER VARYING, nullable): position of the application site
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_schema_directive_arg

An argument the author passed to a schema-level application.

Primary key: (graph_name, directive_name, ordinal, directive_argument_name). Foreign key: (graph_name, directive_name, ordinal) references graphql_schema_directive (graph_name, directive_name, ordinal).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): the owning application’s ordinal
directive_argument_name (CHARACTER VARYING, not null): the definition’s formal argument this value binds
value_sdl (CHARACTER VARYING, not null): the value as written, rendered from the AST; omitted arguments are absent rows

graphql_schema_error

One verdict per row from the two stages that judge the SDL document as a whole, in graphql-java’s own vocabulary. These are the specification’s structural rules, and assembly is the only place they are checked at all: that every named type resolves, that an object satisfies the interfaces it claims, that a directive sits where its definition permits, that the schema has a query root. The stages share this relation because they share a vocabulary, a column set and a grain; splitting them would shatter one ordinal spine to record a difference the stage column already carries. Sibling of graphql_syntax_error rather than one relation with it, because the two refresh at different grains: a syntax refusal belongs to one source and refreshes with it, while a verdict here is a fact about the whole file set that no single source owns and that any change must discard wholesale. Rows are written by capture on every pass, assembly running whether or not the assembled schema is then used for anything, so emptiness means the document was read clean rather than unexamined.

Primary key: (graph_name, ordinal). Foreign key: (graph_name) references store_graph (graph_name). Check: "STAGE" IN('REGISTRY', 'ASSEMBLY').

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
ordinal (INTEGER, not null): emit order in the stage’s own error list, 0-based, continuing across both stages; the key’s tie-breaker on the javac_diagnostic convention, which this relation needs because a stage reports as many verdicts as it found and several may share a location
stage (CHARACTER VARYING, not null): which stage refused, a closed CHECK because the toolchain has exactly these two document-wide stages: REGISTRY for combining every parsed source’s definitions into one registry, ASSEMBLY for assembling that registry. Both populations are live and disjoint by construction: the registry stage refuses the duplicate base declarations (a second type of one name, a second definition of one directive, a second schema block), which in a multi-file workspace are precisely the refusals no single source’s parse could see, and the assembly stage refuses everything else. Deliberately not projected onto the union view: a consumer’s fix does not depend on which stage objected, so putting it on the wire would grow the read vocabulary for no reader. It is kept here because it is the provenance the store’s own reasoning needs, and because it is what makes the duplicate-declaration relation’s claim about assembly running upstream checkable from rows instead of asserted in prose
error_class (CHARACTER VARYING, not null): the refusing error’s class name, graphql-java’s own word for what went wrong (MissingTypeError, NonUniqueNameError, DirectiveIllegalLocationError). The only dimension the toolchain publishes: its getErrorType() is uniformly ValidationError across the whole SDL error set and so discriminates nothing. An open column, for the same reason the rejection residue’s variant is open, and rendered onto the union view’s variant column, whose two namespaces cannot collide (a rejection leaf keeps its enclosing classes and is dotted, these are bare)
message (CHARACTER VARYING, not null): the verdict’s rendered message; display material, never a dimension. It is also the only place the offending coordinate appears: graphql-java names types and fields in prose rather than in structured fields, and lifting them out by parsing the message would mint a dimension from display material, which is why the coordinate columns this stratum’s other arms carry are absent here
source_name (CHARACTER VARYING, nullable): the source the verdict points into, as the reader spelled it; NULL where the verdict points nowhere, which is the schema-wide case (a document with no query root names no position). Note the coarseness: graphql-java locates at the enclosing declaration rather than at the offending element, so a field whose type does not resolve is located at its type’s declaration
source_line (INTEGER, nullable): line of the verdict’s location, 1-based; NULL where unlocated, graphql-java’s own (-1, -1) sentinel having been normalised away at the writer
source_column (INTEGER, nullable): column of the verdict’s location, on the same terms as source_line

graphql_syntax_error

One source the parser refused, per row: the first stage of reading a schema, judged one file at a time. Keyed on the source rather than on an emit-order ordinal, alone among this stratum’s arms, because parsing stops at a source’s first syntax error, so at most one row per source is structural rather than incidental, and the key is then the question a reader actually asks ("does this file parse, and where does it fail") answered as a primary-key lookup. The key also satisfies the store header’s requirement that every base relation be partitionable by the source that produced it, which no ordinal-keyed arm of this stratum can claim; that is a property of the key, not a refresh this store performs, since the SDL families are re-walked wholesale per graph from a parse the pipeline pays for anyway and no schema file reaches the source-partitioned refresh path. A row here is what explains a declaration’s absence from the transcription families without implying the author deleted it, which is the difference between an editor reporting a syntax error and an editor reporting every type in the file as unknown. Rows are written by capture on every pass, so emptiness means every source parsed.

Primary key: (graph_name, source_name). Foreign key: (graph_name) references store_graph (graph_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
source_name (CHARACTER VARYING, not null): the refused source, as the reader spelled it (the store_source spelling, which is what the union view projects as well); the key’s second dimension, and always known, because the loader is parsing one named source when the parser refuses it
message (CHARACTER VARYING, not null): the refusal’s reason exactly as the parser wrote it; display material, never a dimension. Verbatim rather than the shortened form the build’s exception renders, on the same terms as this stratum’s other message columns: the parser publishes two message shapes, one of which carries its explanation in a trailing clause and the other of which is nothing but that clause, so any mechanical shortening loses the reason on one shape or the other. It does repeat the location in prose, which the stored coordinate columns also carry; that is the rejection arm’s precedent (its message keeps the coordinate prefix too) and it is display material either way. Deliberately not the file-attributed one-liner the build throws: the file is a column here, so prefixing it in would store the same dimension twice and let the two spellings fork
source_line (INTEGER, nullable): line the parser refused at, 1-based; NULL where it reported no position, which is the rare case of a source whose very first token is unreadable
source_column (INTEGER, nullable): column the parser refused at, on the same terms as source_line

graphql_type

What a named type is: the two attributes of the type itself, hanging off graphql_type_coordinate, which is where the name’s existence now lives and where everything else in the schema anchors. Read from whichever site capture meets first in merge order (macro-contributed sites included), which on a well-formed schema is the base definition; graphql_type_declaration carries every site and the kind each one wrote. Nothing references this relation, deliberately: the split exists so that what a later cadence owns cannot drag the reference web with it, and holding the reference web off the attribute relation is that split doing its job rather than an omission.

Primary key: (graph_name, type_name). Foreign key: (graph_name, type_name) references graphql_type_coordinate (graph_name, type_name). Check: "KIND" IN('OBJECT', 'INTERFACE', 'UNION', 'ENUM', 'INPUT_OBJECT', 'SCALAR').

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the type these attributes describe, anchored by graphql_type_coordinate
kind (CHARACTER VARYING, not null): the first declaration site’s form in merge order (the base definition’s, on a well-formed schema)
description (CHARACTER VARYING, nullable): SDL description string; net-new as a persisted fact (today read live off retained graphql-java objects). Extensions cannot carry descriptions, so this is the base definition’s when one exists

graphql_type_coordinate

A type name exists in this graph: the anchor every SDL fact, every directive decode and every type-keyed derivation hangs off. It carries the key and nothing else, which is what a coordinate relation is for: existence is the whole assertion, and every attribute of the type is a fact some other relation owns at that fact’s own cadence. Split out from graphql_type so the reference web anchors on the earliest cadence an SDL fact can have. A name exists because some declaration site declares or extends it, which the per-file parse settles before anything is composed and before assembly has judged anything; a relation on a later cadence can then be rewritten, withheld or emptied without the facts hanging off the coordinate following it. Anchoring on a composed relation instead makes every per-site fact’s existence conditional on the whole document assembling, and an author mid-edit is exactly the reader who has no assembled document and every per-site fact. The declared-or-extended reading is what makes the site rows' foreign keys structural (capture writes this row before any site row), and on a base-less extension chain (an author error a detection reports) the row still exists, anchored by the extension sites.

Primary key: (graph_name, type_name). Foreign key: (graph_name) references store_graph (graph_name).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type name as some declaration site spells it; the coordinate every other SDL fact hangs off

graphql_type_declaration

A declaration site of a type: the base definition or one extension. All five extension kinds are live today, so a type’s effective shape may be assembled from several files; this relation records who contributed what and indexes the incremental-refresh unit ("which types does this file touch"). Engine-provided types (built-in scalars) have no declaration rows.

Primary key: (graph_name, type_name, source_name, source_line, source_column). Foreign key: (graph_name, type_name) references graphql_type_coordinate (graph_name, type_name). Check: "KIND" IN('OBJECT', 'INTERFACE', 'UNION', 'ENUM', 'INPUT_OBJECT', 'SCALAR').

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the type this site declares or extends
source_name (CHARACTER VARYING, not null): the site’s file; a site is a syntactic occurrence, so its location is its identity
source_line (INTEGER, not null): line of the site, 1-based
source_column (INTEGER, not null): in the key because a line does not identify a site: two extensions of one type can share a line in minified SDL
merge_ordinal (INTEGER, not null): capture-assigned position in merge order: the base definition, then extensions in document order; on a base-less chain the first extension holds 0. Dense per type (a gate), and the order behind every element ordinal
is_extension (BOOLEAN, not null): FALSE exactly at merge_ordinal 0 on a well-formed schema; a base-less extension chain is an author error a detection reports, never a constraint
kind (CHARACTER VARYING, not null): the declaration form written at this site; a mismatch against the type row’s kind is a detection

graphql_type_directive

A directive is applied to a type (OBJECT, INTERFACE, UNION, ENUM, INPUT_OBJECT, or SCALAR; the parent kind is a join away).

Primary key: (graph_name, type_name, directive_name, ordinal). Foreign key: (graph_name, type_name) references graphql_type_coordinate (graph_name, type_name). Foreign key: (graph_name, type_name, source_name, declaration_line, declaration_column) references graphql_type_declaration (graph_name, type_name, source_name, source_line, source_column).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): as on graphql_schema_directive; federation’s @key repeats here
declaration_line (INTEGER, not null): the applying site (extensions apply type directives too). Every row here is a site the author wrote: no expansion applies a type directive, federation’s synthesized @key being a derivation (intent_synthesized_federation_key) rather than a row in this family
declaration_column (INTEGER, not null): column of the contributing declaration site, the site key’s fourth part
source_name (CHARACTER VARYING, not null): NOT NULL as on graphql_field: half of the site FK
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

graphql_type_directive_arg

An argument the author passed to a type-level application.

Primary key: (graph_name, type_name, directive_name, ordinal, directive_argument_name). Foreign key: (graph_name, type_name, directive_name, ordinal) references graphql_type_directive (graph_name, type_name, directive_name, ordinal).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
type_name (CHARACTER VARYING, not null): the GraphQL type this row is about
directive_name (CHARACTER VARYING, not null): the applied or defined directive name, without the leading @
ordinal (INTEGER, not null): the owning application’s ordinal
directive_argument_name (CHARACTER VARYING, not null): the definition’s formal argument this value binds
value_sdl (CHARACTER VARYING, not null): the value as written, rendered from the AST

graphql_union_member

A union lists a member type.

Primary key: (graph_name, union_name, member_type_name). Foreign key: (graph_name, union_name) references graphql_type_coordinate (graph_name, type_name). Foreign key: (graph_name, union_name, source_name, declaration_line, declaration_column) references graphql_type_declaration (graph_name, type_name, source_name, source_line, source_column).

Columns

graph_name (CHARACTER VARYING, not null): the owning graph’s partition, anchored by store_graph; the leading key dimension that keeps one workspace’s graphs apart
union_name (CHARACTER VARYING, not null): the UNION type listing the member
member_type_name (CHARACTER VARYING, not null): the member type as the union spelled it; author-spelled, no FK
ordinal (INTEGER, not null): position in the effective member list
declaration_line (INTEGER, not null): the contributing site, as on graphql_field
declaration_column (INTEGER, not null): column of the contributing declaration site, the site key’s fourth part
source_name (CHARACTER VARYING, not null): position of the member token itself; NOT NULL as on graphql_field
source_line (INTEGER, nullable): source line, 1-based per the graphql-java convention
source_column (INTEGER, nullable): source column, 1-based per the graphql-java convention

← Schema index