graflo.architecture.schema¶
Modules:
| Name | Description |
|---|---|
anchor |
What a traversal may be anchored on: a complete key, never a property match. |
coerce |
Coerce a raw value — typically text read off a document — to a field's declared type. |
compare |
Graded comparison of a stated value with a stored one, under a field's |
context |
Bounded schema context: the schema graph as a navigable, budgetable object. |
core |
Logical graph model (vertices and edges). |
database_features |
Database-specific schema features. |
db_aware |
DB-aware projections for logical graph configs. |
derive |
Normal forms, parts and keys of field values, and the fields derived from them. |
document |
Full graph schema document (metadata + core + DB profile). |
edge |
Edge configuration and management for graph databases. |
edge_direction |
What each backend can do with edge direction (a capability table, never raises). |
graflo_output |
GraFlo typed output: full schema document plus graph data. |
hierarchy |
Class and relation hierarchies: what |
identity_digest |
Deterministic digest identity for hash-mode and funnel-mode vertices. |
identity_funnel |
Identity funnel: ordered fallback branches for synthetic vertex keys. |
identity_uuid |
UUID identity helpers for assigned mode and UUID-typed natural keys. |
inverse_realization |
How declared inverses are realized, and what is wrong with a realization. |
key_contract |
A vertex type's key contract, in terms any schema language can state. |
metadata |
Schema metadata and versioning. |
namespace |
Physical graph namespace: the database, graph or space a schema deploys into. |
naming |
Declared naming style for the identifiers a schema invents. |
physical_keys |
Translate document keys between logical and stored property names. |
projection |
Pure schema-slicing kernel: induced selection and standalone slice assembly. |
provenance |
Where an artifact came from, carried inside the artifact. |
semantics |
Optional grounding of schema elements in external vocabularies. |
vertex |
Vertex configuration and management for graph databases. |
Attributes¶
GraphModel = CoreSchema
module-attribute
¶
__all__ = ['CoreSchema', 'EdgeConfigDBAware', 'EdgeRuntime', 'GraFloOutput', 'GraphMetadata', 'GraphModel', 'Schema', 'SchemaDBAware', 'VertexConfigDBAware']
module-attribute
¶
Classes¶
CoreSchema
¶
Bases: ConfigBaseModel
Logical graph model (A): vertices and edges.
Source code in graflo/architecture/schema/core.py
Attributes¶
edge_config = PydanticField(..., description='Configuration for edge collections (edges, weights).')
class-attribute
instance-attribute
¶
vertex_config = PydanticField(..., description='Configuration for vertex collections (vertices, identities, properties).')
class-attribute
instance-attribute
¶
Methods:¶
finish_init()
¶
remove_disconnected_vertices()
¶
Remove disconnected vertices and return removed names.
A superclass of a connected vertex stays: it is part of that vertex's meaning, and removing it would leave its subclass naming nothing.
Source code in graflo/architecture/schema/core.py
EdgeConfigDBAware
¶
DB-aware projection wrapper for EdgeConfig.
Source code in graflo/architecture/schema/db_aware.py
321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | |
Attributes¶
db_profile = database_features
instance-attribute
¶
edges
property
¶
ingestion_overlay = ingestion_overlay
instance-attribute
¶
logical = logical
instance-attribute
¶
vertex_config = vertex_config
instance-attribute
¶
vertices
property
¶
Methods:¶
__init__(logical, vertex_config, database_features, ingestion_overlay=None)
¶
Source code in graflo/architecture/schema/db_aware.py
__iter__()
¶
compile_identity_indexes()
¶
Source code in graflo/architecture/schema/db_aware.py
effective_weights(edge)
¶
Source code in graflo/architecture/schema/db_aware.py
items()
¶
relation_dbname(edge)
¶
Source code in graflo/architecture/schema/db_aware.py
relationship_merge_property_names(edge)
¶
Relationship properties that, with the endpoints, key an edge (per backend).
An edge is keyed by its endpoints and relation. The first logical
identities key adds the properties it names, which is how parallel
edges between the same two vertices stay distinct; every other property
is written, never matched on. Additional identities keys are
compiled into separate indexes via :meth:compile_identity_indexes but
do not change the writer's key. Without identities the list is empty.
Source code in graflo/architecture/schema/db_aware.py
runtime(edge)
¶
Source code in graflo/architecture/schema/db_aware.py
EdgeRuntime
dataclass
¶
Resolved DB-facing runtime data for one logical edge.
Source code in graflo/architecture/schema/db_aware.py
Attributes¶
db_profile
instance-attribute
¶
edge
instance-attribute
¶
edge_id
property
¶
effective_relation_field
instance-attribute
¶
relation_name
instance-attribute
¶
source_storage
instance-attribute
¶
store_extracted_relation_as_weight
instance-attribute
¶
target_storage
instance-attribute
¶
Methods:¶
__init__(edge, source_storage, target_storage, relation_name, store_extracted_relation_as_weight, effective_relation_field, db_profile)
¶
graph_name(*, purpose=None)
¶
physical_variants()
¶
storage_name(*, purpose=None)
¶
Source code in graflo/architecture/schema/db_aware.py
GraFloOutput
¶
Bases: ConfigBaseModel
Self-describing GraFlo dataset: schema metadata/profile and graph data.
Source code in graflo/architecture/schema/graflo_output.py
Attributes¶
core_schema
property
¶
Logical graph model (vertices and edges) from :attr:graph_schema.
data = PydanticField(..., description='Graph data container (vertices, edges, lineage).')
class-attribute
instance-attribute
¶
graph_schema = PydanticField(..., description='Full graph schema (metadata, core schema, db profile).', validation_alias=AliasChoices('schema', 'graph_schema'), serialization_alias='schema')
class-attribute
instance-attribute
¶
GraphMetadata
¶
Bases: ConfigBaseModel
Schema metadata and versioning information.
Holds metadata about the schema, including its name, version, and description. Used for schema identification and versioning. Suitable for LLM-generated schema constituents.
Source code in graflo/architecture/schema/metadata.py
Attributes¶
base_iri = PydanticField(default=None, description='Namespace this schema mints IRIs in: a vertex ``Person`` is ``{base_iri}Person``. Ends in ``/`` or ``#``. Not ``db_profile.target_namespace``, which names a database.')
class-attribute
instance-attribute
¶
description = PydanticField(default=None, description='Optional human-readable description of the schema.')
class-attribute
instance-attribute
¶
name = PydanticField(..., description='Label of the schema. Free-form, not an identifier: merges fold it into ``left+right``. The database / graph / space it deploys into is ``db_profile.target_namespace`` when set, else this label sanitized per flavor (see ``Schema.effective_namespace``).')
class-attribute
instance-attribute
¶
namespaces = PydanticField(default_factory=dict, description="Prefix -> namespace IRI for the vocabularies the schema's IRIs come from, e.g. ``{schema: https://schema.org/}``.")
class-attribute
instance-attribute
¶
naming = PydanticField(default=None, description="Optional declaration of the naming style this schema's invented identifiers follow. Purely descriptive: nothing consults it at runtime. Its audience is the next author — human or agent — extending this schema, who would otherwise have to infer the convention from the names and usually infers it wrong.")
class-attribute
instance-attribute
¶
provenance = PydanticField(default=None, description='Content address and lineage of this schema. Written at commit points, never by `apply_evolution`, and excluded from every content hash -- identity has to be path-independent.')
class-attribute
instance-attribute
¶
semantics = PydanticField(default=None, description='Optional external-vocabulary anchors for the schema as a whole.')
class-attribute
instance-attribute
¶
version = PydanticField(default=None, description="Semantic version of the schema (e.g. '1.0.0', '2.1.3-beta+build.42').")
class-attribute
instance-attribute
¶
Schema
¶
Bases: ConfigBaseModel
Graph schema (A+B): metadata, core schema, and DB profile.
Source code in graflo/architecture/schema/document.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | |
Attributes¶
core_schema = PydanticField(..., description='Core schema model (vertices + edges).', validation_alias=AliasChoices('core_schema', 'graph'))
class-attribute
instance-attribute
¶
db_profile = PydanticField(default_factory=DatabaseProfile, description='Database-specific physical profile (secondary indexes, naming, TigerGraph GSQL DEFAULT overrides via default_property_values, etc.).')
class-attribute
instance-attribute
¶
metadata = PydanticField(..., description='Schema metadata and versioning (name, version).')
class-attribute
instance-attribute
¶
Methods:¶
default_dump_filename()
¶
Return default schema dump filename:
Source code in graflo/architecture/schema/document.py
dump(path=None, *, exclude_defaults=True)
¶
Dump schema YAML to path, excluding defaults by default.
If path is omitted, writes into current working directory using
<schema_name>-<version>.yaml.
Source code in graflo/architecture/schema/document.py
effective_namespace(db_flavor=None, override=None)
¶
The database / graph / space this schema deploys into on db_flavor.
metadata.name is a label; this is the identifier. See
:func:~graflo.architecture.schema.namespace.resolve_namespace for the
precedence (override, db_profile.target_namespace, sanitized name).
Source code in graflo/architecture/schema/document.py
finish_init()
¶
Source code in graflo/architecture/schema/document.py
remove_disconnected_vertices()
¶
reserved_fields()
¶
Names of every reserved field, on any vertex or edge type.
Source code in graflo/architecture/schema/document.py
resolve_db_aware(db_flavor=None)
¶
Build DB-aware runtime wrappers for db_flavor.
Non-mutating: when db_flavor differs from the authored profile, the
wrappers are built over a copy. This used to assign onto
self.db_profile, which made the schema's flavor a function of
whoever resolved it last — fine while resolution only ever happened once
per ingest, wrong as soon as two readers want two different targets from
one shared Schema.
Source code in graflo/architecture/schema/document.py
SchemaDBAware
dataclass
¶
DB-aware schema runtime view.
Source code in graflo/architecture/schema/db_aware.py
VertexConfigDBAware
¶
DB-aware projection wrapper for VertexConfig.
Source code in graflo/architecture/schema/db_aware.py
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 | |
Attributes¶
assigned_vertices
property
¶
blank_vertices
property
¶
db_profile = database_features
instance-attribute
¶
hash_identity_vertices
property
¶
logical = logical
instance-attribute
¶
vertex_set
property
¶
vertices
property
¶
Methods:¶
__init__(logical, database_features)
¶
compile_secondary_identity_indexes()
¶
Register a lookup index for every declared secondary identity.
has_vertex(name)
¶
identity_fields(vertex_name)
¶
Source code in graflo/architecture/schema/db_aware.py
index(vertex_name)
¶
Get primary index for a vertex (DB layer needs Index for collection setup).
is_assigned(name)
¶
is_blank(name)
¶
is_hash_identity(name)
¶
match_fields(vertex_name, selector)
¶
Fields an edge endpoint is matched on, with DB-aware identity fallback.