Entity Metadata Querying

Relevant source files

The following files were used as context for generating this wiki page:

• CHANGELOG.md
• src/builder.rs
• examples/postgres/tests/entity_metadata_tests.rs
• generator/src/writer.rs
• src/lib.rs

Entity Metadata Querying is a specialized feature within Seaography that allows users to programmatically inspect the underlying SeaORM entity schema via GraphQL. Introduced in version 1.1.4, this system exposes a dedicated query field, _sea_orm_entity_metadata, which provides detailed information about table structures, including column names, nullability, data types (primitive, array, or enumeration), and primary key definitions.

This feature is primary driven by the schema-meta feature flag and is integrated into the core Builder logic. It bridges the gap between the dynamic GraphQL schema and the static SeaORM models by serializing entity definitions into a queryable metadata format.

Architecture and Internal Storage

The metadata system relies on a central registry within the Builder class to store JSON representations of SeaORM entities. When an entity is registered with the builder, Seaography uses the database backend to generate a JSON schema of the entity, which is then cached for later retrieval by the GraphQL resolver.

Metadata Registration Flow

The Builder maintains a MetadataHashMap which maps table names to their respective serde_json::Value schema representations.

The diagram shows the lifecycle of metadata from entity registration to availability in the GraphQL schema.
Sources: src/builder.rs:65, src/builder.rs:163-165

The Metadata Resolver

The query field _sea_orm_entity_metadata is implemented as a dynamic field on the Root Query object. It accepts a table_name argument and performs a lookup in the internal metadata hashmap.

• Logic: It takes the internal metadata, clones it into the resolver closure, and attempts to match the requested table_name.
• Transformation: If a match is found, the JSON value is deserialized into a Table struct and returned as a FieldValue::owned_any.

Sources: src/builder.rs:264-297

Data Models and Types

The metadata API exposes several specialized output types to represent the database schema accurately within GraphQL.

Metadata Components

Component	Description
Table	The root metadata object containing a list of columns and the primary key list.
Column	Represents a single database field, including its name, nullability, and type details.
ColumnType	A complex object defining if a type is a primitive (e.g., string, integer), an array, or an enumeration.
Enumeration	Details for enum types, including the type name and all possible variants.

Sources: src/builder.rs:267-271, examples/postgres/tests/entity_metadata_tests.rs:37-56

Primary Key Representation

Primary keys are returned as a list of strings representing the column names that form the unique identifier for the entity.
Sources: examples/postgres/tests/entity_metadata_tests.rs:57-59

Querying Metadata

The metadata is accessed through the _sea_orm_entity_metadata field. This is particularly useful for frontend applications that need to dynamically generate forms or documentation based on the database schema.

Example GraphQL Query

{
  city: _sea_orm_entity_metadata(table_name: "city") {
    columns {
      name
      nullable
      type_ {
        primitive
        enumeration {
          name
          variants
        }
      }
    }
    primary_key
  }
}

Sources: examples/postgres/tests/entity_metadata_tests.rs:36-62

Sequence of Retrieval

The sequence diagram illustrates the internal lookup process when a client requests metadata for a specific table.
Sources: src/builder.rs:275-290

Configuration and Feature Flags

Entity metadata querying is not enabled by default. It requires specific crate features to be active.

• Feature Flag: schema-meta. This feature enables the inclusion of the metadata querying modules and derive macros.
• Dependency: Enabling schema-meta also activates macros, serde/derive, and with-postgres-array.

Sources: Cargo.toml:50-52, src/builder.rs:264

Schema Limits

While metadata querying is a management-level feature, it is still subject to the depth_limit and complexity_limit configured in the schema_builder.

Config Parameter	Source	Description
depth	Builder.depth	Maximum nesting depth allowed for the metadata query.
complexity	Builder.complexity	Maximum computational complexity for the metadata query.

Sources: generator/src/writer.rs:94-95, src/builder.rs:395-403

Conclusion

The Entity Metadata Querying system provides a robust introspection layer for Seaography-powered APIs. By leveraging SeaORM's internal schema generation and caching it within the GraphQL builder, the system offers a high-performance way to access database-level details. This enables developers to build more intelligent clients that understand the underlying data constraints, types, and relationships without manual schema duplication.