prograph 1.3.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- prograph-1.3.3.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""PostgreSQL executor for graph queries.
|
|
2
|
+
|
|
3
|
+
Executes graph queries by generating PostgreSQL SQL and running it
|
|
4
|
+
against a PostgreSQL database through its ADBC driver.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Any, Dict, Optional
|
|
8
|
+
|
|
9
|
+
from prograph.executors.base import BaseExecutor
|
|
10
|
+
from prograph.graph.postgresql_graph import PostgreSQLGraph
|
|
11
|
+
from prograph.read_only import ExecutorRefusesWrites
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class PostgreSQLExecutor(ExecutorRefusesWrites, BaseExecutor):
|
|
15
|
+
"""Execute graph queries against a PostgreSQL database.
|
|
16
|
+
|
|
17
|
+
Generates PostgreSQL SQL from graph queries and executes them
|
|
18
|
+
against the provided database connection.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
def __init__(
|
|
22
|
+
self,
|
|
23
|
+
schema: Any,
|
|
24
|
+
connection: Any,
|
|
25
|
+
table_stats: Optional[Dict[str, int]] = None,
|
|
26
|
+
):
|
|
27
|
+
"""Initialize the PostgreSQL executor.
|
|
28
|
+
|
|
29
|
+
Args:
|
|
30
|
+
schema: GraphSchema with node/relationship mappings
|
|
31
|
+
connection: a PostgreSQL URI, or an ADBC connection
|
|
32
|
+
table_stats: Optional table row counts for optimization
|
|
33
|
+
"""
|
|
34
|
+
self.schema = schema
|
|
35
|
+
self.graph = PostgreSQLGraph(schema, connection, table_stats=table_stats)
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"""Spark executor for graph queries over Spark DataFrames.
|
|
2
|
+
|
|
3
|
+
This executor enables graph queries against Spark DataFrames
|
|
4
|
+
using a schema mapping to define the virtual graph structure.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Dict
|
|
8
|
+
|
|
9
|
+
try:
|
|
10
|
+
from pyspark.sql import DataFrame as SparkDataFrame
|
|
11
|
+
SPARK_AVAILABLE = True
|
|
12
|
+
except ImportError:
|
|
13
|
+
SPARK_AVAILABLE = False
|
|
14
|
+
SparkDataFrame = None
|
|
15
|
+
|
|
16
|
+
from prograph.executors.base import BaseExecutor
|
|
17
|
+
from prograph.graph.spark_graph import SparkGraph
|
|
18
|
+
from prograph.schema.mapping import GraphSchema
|
|
19
|
+
from prograph.read_only import ExecutorRefusesWrites
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class SparkExecutor(ExecutorRefusesWrites, BaseExecutor):
|
|
23
|
+
"""Execute graph queries against Spark DataFrames.
|
|
24
|
+
|
|
25
|
+
This executor provides a read-only virtual graph over Spark DataFrames.
|
|
26
|
+
CREATE, DELETE, and other mutating operations are not supported.
|
|
27
|
+
|
|
28
|
+
Example:
|
|
29
|
+
>>> schema = GraphSchema()
|
|
30
|
+
>>> schema.add_node_mapping(NodeMapping(
|
|
31
|
+
... source_table='movies',
|
|
32
|
+
... label='Movie',
|
|
33
|
+
... id_column='movie_id',
|
|
34
|
+
... property_columns={'title': 'title'}
|
|
35
|
+
... ))
|
|
36
|
+
>>> executor = SparkExecutor(schema, {'movies': movies_df})
|
|
37
|
+
>>> # Use with ProGraph
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
def __init__(
|
|
41
|
+
self,
|
|
42
|
+
schema: GraphSchema,
|
|
43
|
+
dataframes: Dict[str, 'SparkDataFrame'],
|
|
44
|
+
sql_warehouse_id: str = None,
|
|
45
|
+
warehouse_timeout: float = None,
|
|
46
|
+
ansi_session: bool = True,
|
|
47
|
+
):
|
|
48
|
+
"""Initialize the Spark executor.
|
|
49
|
+
|
|
50
|
+
Args:
|
|
51
|
+
schema: GraphSchema defining node and relationship mappings
|
|
52
|
+
dataframes: Dictionary mapping table names to Spark DataFrames
|
|
53
|
+
sql_warehouse_id: Optional Databricks SQL Warehouse ID for optimized
|
|
54
|
+
SQL execution. When provided, generated SQL queries are routed to
|
|
55
|
+
the warehouse instead of Spark compute.
|
|
56
|
+
warehouse_timeout: Optional timeout in seconds for SQL Warehouse
|
|
57
|
+
queries. When set, queries that exceed this time are cancelled
|
|
58
|
+
on the warehouse and raise TimeoutError. None (default) means
|
|
59
|
+
poll indefinitely until completion.
|
|
60
|
+
ansi_session: Run each SQL statement with ANSI mode on.
|
|
61
|
+
|
|
62
|
+
Raises:
|
|
63
|
+
ImportError: If pyspark is not installed
|
|
64
|
+
ValueError: If schema or dataframes is invalid
|
|
65
|
+
"""
|
|
66
|
+
if not SPARK_AVAILABLE:
|
|
67
|
+
raise ImportError(
|
|
68
|
+
"pyspark is required for the Spark backend. "
|
|
69
|
+
"Install it with: pip install pyspark"
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
if schema is None:
|
|
73
|
+
raise ValueError("schema is required for Spark backend")
|
|
74
|
+
if dataframes is None:
|
|
75
|
+
raise ValueError("dataframes dict is required for Spark backend")
|
|
76
|
+
|
|
77
|
+
self.schema = schema
|
|
78
|
+
self.dataframes = dataframes
|
|
79
|
+
self.graph = SparkGraph(
|
|
80
|
+
schema, dataframes,
|
|
81
|
+
sql_warehouse_id=sql_warehouse_id,
|
|
82
|
+
warehouse_timeout=warehouse_timeout,
|
|
83
|
+
ansi_session=ansi_session,
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def __repr__(self) -> str:
|
|
88
|
+
return f"SparkExecutor({self.graph})"
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""SQL Server executor for graph queries.
|
|
2
|
+
|
|
3
|
+
Executes graph queries by generating SQL Server SQL and running it
|
|
4
|
+
against a SQL Server database via SQLAlchemy or pyodbc.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Any, Dict, Optional
|
|
8
|
+
|
|
9
|
+
from prograph.executors.base import BaseExecutor
|
|
10
|
+
from prograph.graph.sqlserver_graph import SQLServerGraph
|
|
11
|
+
from prograph.read_only import ExecutorRefusesWrites
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class SQLServerExecutor(ExecutorRefusesWrites, BaseExecutor):
|
|
15
|
+
"""Execute graph queries against a SQL Server database.
|
|
16
|
+
|
|
17
|
+
Generates SQL Server SQL from graph queries and executes them
|
|
18
|
+
against the provided database connection.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
def __init__(
|
|
22
|
+
self,
|
|
23
|
+
schema: Any,
|
|
24
|
+
connection: Any,
|
|
25
|
+
table_stats: Optional[Dict[str, int]] = None,
|
|
26
|
+
):
|
|
27
|
+
"""Initialize the SQL Server executor.
|
|
28
|
+
|
|
29
|
+
Args:
|
|
30
|
+
schema: GraphSchema with node/relationship mappings
|
|
31
|
+
connection: SQLAlchemy engine or pyodbc connection
|
|
32
|
+
table_stats: Optional table row counts for optimization
|
|
33
|
+
"""
|
|
34
|
+
self.schema = schema
|
|
35
|
+
self.graph = SQLServerGraph(schema, connection, table_stats=table_stats)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Helpers built on ProGraph's public API, outside the engine."""
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""GraphQL over a ProGraph engine: a schema generated from the engine's schema. Queries
|
|
2
|
+
are not supported in 1.x: `execute_graphql` raises `GraphQLNotInReleaseError`.
|
|
3
|
+
|
|
4
|
+
Experimental: an extra outside ProGraph's engine API, and an exploration. Its schema, arguments and output may
|
|
5
|
+
change between releases. Needs graphql-core (`pip install "prograph[graphql]"`).
|
|
6
|
+
|
|
7
|
+
from prograph.extras.graphql import execute_graphql, graphql_schema
|
|
8
|
+
print(graphql_schema(engine)) # the schema, in SDL
|
|
9
|
+
execute_graphql(engine, "{ person(where: {age_gt: 26}) { name knows { name } } }")
|
|
10
|
+
|
|
11
|
+
The generated schema (`schema.py`) and how an operation is read (`execute.py`) are described in those modules;
|
|
12
|
+
docs/guides/graphql.md is the guide.
|
|
13
|
+
"""
|
|
14
|
+
try:
|
|
15
|
+
import graphql # noqa: F401
|
|
16
|
+
except ImportError as e: # pragma: no cover - the message is the point
|
|
17
|
+
raise ImportError('prograph.extras.graphql needs graphql-core: pip install "prograph[graphql]"') from e
|
|
18
|
+
if not graphql.__version__.startswith("3.2."): # pragma: no cover
|
|
19
|
+
# 3.3 changes the execution helpers' return types (get_variable_values gives a VariableValues)
|
|
20
|
+
raise ImportError(f"prograph.extras.graphql needs graphql-core 3.2, not {graphql.__version__}: "
|
|
21
|
+
f'pip install "graphql-core>=3.2,<3.3"')
|
|
22
|
+
|
|
23
|
+
from .execute import execute_graphql, node_id # noqa: E402
|
|
24
|
+
from .schema import GraphQLSchemaError, build_model, graphql_name # noqa: E402
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def graphql_schema(engine, required=None) -> str:
|
|
28
|
+
"""The engine's generated GraphQL schema, in the schema definition language."""
|
|
29
|
+
from graphql import print_schema
|
|
30
|
+
return print_schema(build_model(engine, required).schema)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
__all__ = ["execute_graphql", "graphql_schema", "build_model", "node_id", "graphql_name", "GraphQLSchemaError"]
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""GraphQL queries over a ProGraph engine: not supported in 1.x.
|
|
2
|
+
|
|
3
|
+
The extra answered a GraphQL operation by reading the data one level at a time in Cypher, which is not built
|
|
4
|
+
for it. `execute_graphql` refuses with `GraphQLNotInReleaseError`; the
|
|
5
|
+
reader is in git at the `pre-1.0.0` tag. The generated schema
|
|
6
|
+
(`schema.py`, `graphql_schema`) reads the mapping only and works.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from typing import Any, Dict, List, Optional, Tuple
|
|
11
|
+
from urllib.parse import quote
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def node_id(label: str, key: Any) -> str:
|
|
15
|
+
"""The opaque identity of a node: its label and key, each percent-encoded, so that `node(id:)` reads it back.
|
|
16
|
+
Not elementId's text (whose format is not a contract)."""
|
|
17
|
+
return f"{quote(label, safe='')}:{quote(str(key), safe='')}"
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def execute_graphql(engine: Any, query: str, variables: Optional[Dict[str, Any]] = None,
|
|
21
|
+
operation_name: Optional[str] = None, *, model: Any = None,
|
|
22
|
+
trace: Optional[List[Tuple[str, float]]] = None) -> Dict[str, Any]:
|
|
23
|
+
"""Not supported in 1.x: raises `GraphQLNotInReleaseError` before anything runs (the extra answers in Cypher)."""
|
|
24
|
+
from prograph.utils.exceptions import GraphQLNotInReleaseError
|
|
25
|
+
raise GraphQLNotInReleaseError()
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
"""A GraphQL schema for a ProGraph schema, generated from `engine.schema.describe()` and the recorded column types.
|
|
2
|
+
|
|
3
|
+
- Each node label is an object type implementing `Node`, with `id: ID!` (an opaque identity: the label and the
|
|
4
|
+
node's key, read back by `node(id:)`) and a field for each property.
|
|
5
|
+
- Each relationship type is a list field on its start type (`knows`, from KNOWS) and, read backwards, on its end
|
|
6
|
+
type (`inverseKnows`); `knowsEdges` and `inverseKnowsEdges` give the relationship's own properties beside the
|
|
7
|
+
node at its other end. One field per relationship: two parallel KNOWS from one person to another are two items.
|
|
8
|
+
- `Query` has one list field per label (`person`), with `where`, `orderBy`, `first` and `offset`, and `node(id:)`.
|
|
9
|
+
- No `Mutation` and no `Subscription`: ProGraph does not write.
|
|
10
|
+
|
|
11
|
+
GraphQL names are made from the schema's names by one rule (`graphql_name`); two that come out the same are
|
|
12
|
+
refused by name, never renamed a second time.
|
|
13
|
+
"""
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import datetime
|
|
17
|
+
import re
|
|
18
|
+
from dataclasses import dataclass, field
|
|
19
|
+
from decimal import Decimal
|
|
20
|
+
from typing import Any, Callable, Dict, List, Optional, Tuple
|
|
21
|
+
|
|
22
|
+
from graphql import (
|
|
23
|
+
GraphQLArgument, GraphQLBoolean, GraphQLEnumType, GraphQLEnumValue, GraphQLField, GraphQLFloat, GraphQLID,
|
|
24
|
+
GraphQLInputField, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull,
|
|
25
|
+
GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString,
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class GraphQLSchemaError(ValueError):
|
|
30
|
+
"""The ProGraph schema cannot be given a GraphQL schema as it stands (a name collision, a composite key)."""
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
# ------------------------------------------------------------------------------------------------ scalars
|
|
34
|
+
|
|
35
|
+
def _text(value: Any) -> str:
|
|
36
|
+
return value.isoformat() if hasattr(value, "isoformat") else str(value)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _long(value: Any) -> int:
|
|
40
|
+
if isinstance(value, bool) or not isinstance(value, int):
|
|
41
|
+
raise TypeError(f"Long cannot represent {value!r}")
|
|
42
|
+
return value
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _checked(kind: str, read: Callable[[str], Any]) -> Callable[[Any], str]:
|
|
46
|
+
"""An input coercion that accepts only text `read` can read, and gives back the text: a bad value is a
|
|
47
|
+
GraphQL error at coercion (GraphQL spec, 5.6.1 for literals, 6.1.2 for variables), never later."""
|
|
48
|
+
def parse(value: Any) -> str:
|
|
49
|
+
if not isinstance(value, str):
|
|
50
|
+
raise TypeError(f"{kind} cannot represent a non-string value: {value!r}")
|
|
51
|
+
try:
|
|
52
|
+
read(value)
|
|
53
|
+
except (ValueError, ArithmeticError) as e:
|
|
54
|
+
raise ValueError(f"{kind} cannot represent {value!r}") from e
|
|
55
|
+
return value
|
|
56
|
+
return parse
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _finite_decimal(text: str) -> Decimal:
|
|
60
|
+
d = Decimal(text)
|
|
61
|
+
if not d.is_finite():
|
|
62
|
+
raise ValueError(text)
|
|
63
|
+
return d
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
# GraphQL's Int is 32-bit (GraphQL spec, 3.5.1); a ProGraph integer is 64-bit, so an integer column is a Long.
|
|
67
|
+
LONG = GraphQLScalarType("Long", description="A 64-bit integer, as a JSON number.",
|
|
68
|
+
serialize=_long, parse_value=_long)
|
|
69
|
+
DECIMAL = GraphQLScalarType("Decimal", description="An exact decimal, as its text (\"12.50\"), so no digit is lost.",
|
|
70
|
+
serialize=_text, parse_value=_checked("Decimal", _finite_decimal))
|
|
71
|
+
DATE = GraphQLScalarType("Date", description="A date, as ISO 8601 text (\"2026-11-05\").",
|
|
72
|
+
serialize=_text, parse_value=_checked("Date", datetime.date.fromisoformat))
|
|
73
|
+
DATETIME = GraphQLScalarType("DateTime", description="A date and time, as ISO 8601 text.",
|
|
74
|
+
serialize=_text, parse_value=_checked("DateTime", datetime.datetime.fromisoformat))
|
|
75
|
+
_SCALARS = {"INTEGER": LONG, "FLOAT": GraphQLFloat, "STRING": GraphQLString, "BOOLEAN": GraphQLBoolean,
|
|
76
|
+
"DECIMAL": DECIMAL, "DATE": DATE, "DATETIME": DATETIME, "LOCALDATETIME": DATETIME}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _scalar_of(cypher_type: Any):
|
|
80
|
+
"""The GraphQL scalar for a recorded column type; String where the source recorded none, or a kind this
|
|
81
|
+
module does not map (a list, a map, a time), whose value is given as its text."""
|
|
82
|
+
if cypher_type is None:
|
|
83
|
+
return GraphQLString
|
|
84
|
+
if getattr(cypher_type, "exact", False): # a DECIMAL is the float kind, exact (prograph.schema.types)
|
|
85
|
+
return DECIMAL
|
|
86
|
+
kind = str(getattr(cypher_type, "kind", cypher_type)).upper()
|
|
87
|
+
return _SCALARS.get(kind, GraphQLString)
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
# ------------------------------------------------------------------------------------------------ names
|
|
91
|
+
|
|
92
|
+
_NAME = re.compile(r"^[_A-Za-z][_0-9A-Za-z]*$")
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def graphql_name(name: str) -> str:
|
|
96
|
+
"""A legal GraphQL name (GraphQL spec, 2.1.9) from a schema name: every other character becomes "_", a
|
|
97
|
+
leading digit gets a "_" before it, and a leading "__" (reserved for introspection) keeps one "_"."""
|
|
98
|
+
out = re.sub(r"[^_0-9A-Za-z]", "_", name)
|
|
99
|
+
if not out or out[0].isdigit():
|
|
100
|
+
out = "_" + out
|
|
101
|
+
while out.startswith("__"):
|
|
102
|
+
out = out[1:]
|
|
103
|
+
return out
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def _camel(rel_type: str) -> str:
|
|
107
|
+
"""KNOWS -> knows, LIVES_IN -> livesIn, worksFor -> worksFor."""
|
|
108
|
+
if rel_type.upper() == rel_type:
|
|
109
|
+
words = [w for w in rel_type.lower().split("_") if w]
|
|
110
|
+
return graphql_name(words[0] + "".join(w.capitalize() for w in words[1:])) if words else graphql_name(rel_type)
|
|
111
|
+
return graphql_name(rel_type[0].lower() + rel_type[1:])
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
# ------------------------------------------------------------------------------------------------ the model
|
|
115
|
+
|
|
116
|
+
@dataclass
|
|
117
|
+
class Prop:
|
|
118
|
+
field: str # GraphQL field name
|
|
119
|
+
name: str # ProGraph property name (what Cypher reads)
|
|
120
|
+
scalar: Any
|
|
121
|
+
required: bool = False
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@dataclass
|
|
125
|
+
class Rel:
|
|
126
|
+
field: str # the node list field (knows, inverseKnows)
|
|
127
|
+
edges_field: str # the edge list field (knowsEdges)
|
|
128
|
+
rel_type: str
|
|
129
|
+
inverse: bool # read from the end node back to the start
|
|
130
|
+
target: str # the label at the other end
|
|
131
|
+
props: List[Prop] = field(default_factory=list)
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
@dataclass
|
|
135
|
+
class Label:
|
|
136
|
+
label: str
|
|
137
|
+
type_name: str
|
|
138
|
+
root_field: str
|
|
139
|
+
key: str # the key column, readable in Cypher as a property
|
|
140
|
+
key_kind: str = "STRING" # the key column's recorded kind: an id's key text is read back as it
|
|
141
|
+
props: Dict[str, Prop] = field(default_factory=dict) # by GraphQL field
|
|
142
|
+
rels: Dict[str, Rel] = field(default_factory=dict) # by node list field or edge list field
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
@dataclass
|
|
146
|
+
class Model:
|
|
147
|
+
labels: Dict[str, Label] # by label
|
|
148
|
+
by_type: Dict[str, Label] # by GraphQL type name
|
|
149
|
+
schema: GraphQLSchema = None
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _claim(names: Dict[str, str], name: str, what: str) -> None:
|
|
153
|
+
if name in names:
|
|
154
|
+
raise GraphQLSchemaError(f"{what} and {names[name]} are both named {name!r} in GraphQL; rename one in the "
|
|
155
|
+
f"ProGraph schema (no name is changed a second time)")
|
|
156
|
+
names[name] = what
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
def build_model(engine: Any, required: Optional[Dict[str, List[str]]] = None) -> Model:
|
|
160
|
+
"""The model of the GraphQL schema: which label, property and relationship each type and field reads.
|
|
161
|
+
`required` names properties to type non-null (`{"Person": ["name"]}`): the schema does not say a column has
|
|
162
|
+
no nulls, so a property is nullable unless the caller says so; a node whose required property is null is
|
|
163
|
+
then an error, which GraphQL propagates to the nearest nullable field (GraphQL spec, 6.4.4)."""
|
|
164
|
+
from prograph.r2rml.schema import require_property_graph
|
|
165
|
+
require_property_graph(engine.schema, "GraphQL")
|
|
166
|
+
required = required or {}
|
|
167
|
+
described = engine.schema.describe()
|
|
168
|
+
mappings = {m.label: m for m in engine.schema.node_mappings if m.label is not None}
|
|
169
|
+
rel_mappings = {(m.rel_type, m.start_node_label, m.end_node_label): m for m in engine.schema.relationship_mappings}
|
|
170
|
+
labels: Dict[str, Label] = {}
|
|
171
|
+
type_names: Dict[str, str] = {"Query": "the query type", "Node": "the Node interface", "Long": "a scalar",
|
|
172
|
+
"Decimal": "a scalar", "Date": "a scalar", "DateTime": "a scalar",
|
|
173
|
+
"SortDirection": "an enum"}
|
|
174
|
+
root_fields: Dict[str, str] = {"node": "the node(id:) lookup"}
|
|
175
|
+
for node in described.nodes:
|
|
176
|
+
if node.label is None:
|
|
177
|
+
continue # an unlabelled node mapping: GraphQL types are labels
|
|
178
|
+
if len(node.id_columns) != 1:
|
|
179
|
+
raise GraphQLSchemaError(f"label {node.label!r} has a composite key {node.id_columns}; this exploration "
|
|
180
|
+
f"reads labels with a one-column key only")
|
|
181
|
+
type_name = graphql_name(node.label)
|
|
182
|
+
_claim(type_names, type_name, f"label {node.label!r}")
|
|
183
|
+
for suffix in ("Where", "OrderBy", "Edge"):
|
|
184
|
+
_claim(type_names, type_name + suffix, f"label {node.label!r}'s {suffix} type")
|
|
185
|
+
root = graphql_name(node.label[0].lower() + node.label[1:])
|
|
186
|
+
_claim(root_fields, root, f"label {node.label!r}")
|
|
187
|
+
mapping = mappings[node.label]
|
|
188
|
+
key_type = engine.schema.column_type(mapping, node.id_columns[0])
|
|
189
|
+
entry = Label(node.label, type_name, root, node.id_columns[0],
|
|
190
|
+
"DECIMAL" if getattr(key_type, "exact", False)
|
|
191
|
+
else str(getattr(key_type, "kind", key_type or "STRING")).upper())
|
|
192
|
+
fields: Dict[str, str] = {"id": "the identity"}
|
|
193
|
+
filters: Dict[str, str] = {"id": "the id filter", "id_in": "the id filter", "AND": "AND", "OR": "OR",
|
|
194
|
+
"NOT": "NOT"}
|
|
195
|
+
for p in node.properties:
|
|
196
|
+
name = graphql_name(p.name)
|
|
197
|
+
_claim(fields, name, f"property {p.name!r} of {node.label!r}")
|
|
198
|
+
for suffix in ("", "_not", "_in", "_lt", "_lte", "_gt", "_gte"):
|
|
199
|
+
_claim(filters, name + suffix, f"{node.label!r}'s filter on property {p.name!r}")
|
|
200
|
+
entry.props[name] = Prop(name, p.name, _scalar_of(engine.schema.column_type(mapping, p.column)),
|
|
201
|
+
required=p.name in required.get(node.label, []))
|
|
202
|
+
unknown = set(required.get(node.label, [])) - {p.name for p in node.properties}
|
|
203
|
+
if unknown:
|
|
204
|
+
raise GraphQLSchemaError(f"required names properties {sorted(unknown)} that {node.label!r} does not have")
|
|
205
|
+
labels[node.label] = entry
|
|
206
|
+
# A relationship type may join one label to several (IS_PART_OF from Component to Engine and to Module): then
|
|
207
|
+
# each field names its far label (isPartOfEngine, isPartOfModule); a type with one far label keeps the short
|
|
208
|
+
# name. One rule, fixed before any name is given, so no name is changed a second time.
|
|
209
|
+
targets: Dict[Tuple[str, str, bool], set] = {}
|
|
210
|
+
# A relationship whose end is no one label (an end given by an identity) has no GraphQL field.
|
|
211
|
+
described_rels = [r for r in described.relationships if r.start_label in labels and r.end_label in labels]
|
|
212
|
+
for rel in described_rels:
|
|
213
|
+
targets.setdefault((rel.start_label, rel.rel_type, False), set()).add(rel.end_label)
|
|
214
|
+
targets.setdefault((rel.end_label, rel.rel_type, True), set()).add(rel.start_label)
|
|
215
|
+
for rel in described_rels:
|
|
216
|
+
mapping = rel_mappings.get((rel.rel_type, rel.start_label, rel.end_label))
|
|
217
|
+
props = []
|
|
218
|
+
names: Dict[str, str] = {"node": "the edge's node"}
|
|
219
|
+
for p in rel.properties:
|
|
220
|
+
name = graphql_name(p.name)
|
|
221
|
+
_claim(names, name, f"property {p.name!r} of {rel.rel_type!r}")
|
|
222
|
+
props.append(Prop(name, p.name, _scalar_of(engine.schema.column_type(mapping, p.column) if mapping else None)))
|
|
223
|
+
out_field = _camel(rel.rel_type)
|
|
224
|
+
in_field = "inverse" + out_field[0].upper() + out_field[1:]
|
|
225
|
+
for owner, other, fname, inverse in ((rel.start_label, rel.end_label, out_field, False),
|
|
226
|
+
(rel.end_label, rel.start_label, in_field, True)):
|
|
227
|
+
if owner not in labels or other not in labels:
|
|
228
|
+
continue
|
|
229
|
+
entry = labels[owner]
|
|
230
|
+
if len(targets[(owner, rel.rel_type, inverse)]) > 1:
|
|
231
|
+
fname = fname + labels[other].type_name
|
|
232
|
+
taken = {"id": "the identity", **{f: f"property {p.name!r}" for f, p in entry.props.items()},
|
|
233
|
+
**{f: f"relationship {r.rel_type!r}" for f, r in entry.rels.items()}}
|
|
234
|
+
what = f"relationship {rel.rel_type!r} ({'into' if inverse else 'out of'} {owner!r})"
|
|
235
|
+
_claim(taken, fname, what)
|
|
236
|
+
_claim(taken, fname + "Edges", what + "'s edges")
|
|
237
|
+
r = Rel(fname, fname + "Edges", rel.rel_type, inverse, other, props)
|
|
238
|
+
entry.rels[fname] = r
|
|
239
|
+
entry.rels[fname + "Edges"] = r
|
|
240
|
+
model = Model(labels, {l.type_name: l for l in labels.values()})
|
|
241
|
+
model.schema = _graphql_schema(model)
|
|
242
|
+
return model
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
# ------------------------------------------------------------------------------------------------ GraphQL types
|
|
246
|
+
|
|
247
|
+
SORT = GraphQLEnumType("SortDirection", {"ASC": GraphQLEnumValue("ASC"), "DESC": GraphQLEnumValue("DESC")})
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _where_type(entry: Label) -> GraphQLInputObjectType:
|
|
251
|
+
def fields():
|
|
252
|
+
out = {"id": GraphQLInputField(GraphQLID), "id_in": GraphQLInputField(GraphQLList(GraphQLNonNull(GraphQLID)))}
|
|
253
|
+
for name, p in entry.props.items():
|
|
254
|
+
out[name] = GraphQLInputField(p.scalar, description="equal to; null means the property has no value")
|
|
255
|
+
out[name + "_not"] = GraphQLInputField(p.scalar, description="not equal to; null means it has a value")
|
|
256
|
+
out[name + "_in"] = GraphQLInputField(GraphQLList(GraphQLNonNull(p.scalar)))
|
|
257
|
+
if p.scalar is not GraphQLBoolean:
|
|
258
|
+
for op in ("lt", "lte", "gt", "gte"):
|
|
259
|
+
out[f"{name}_{op}"] = GraphQLInputField(p.scalar)
|
|
260
|
+
out["AND"] = GraphQLInputField(GraphQLList(GraphQLNonNull(where)))
|
|
261
|
+
out["OR"] = GraphQLInputField(GraphQLList(GraphQLNonNull(where)))
|
|
262
|
+
out["NOT"] = GraphQLInputField(where)
|
|
263
|
+
return out
|
|
264
|
+
where = GraphQLInputObjectType(entry.type_name + "Where", fields)
|
|
265
|
+
return where
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
def _order_type(entry: Label) -> GraphQLInputObjectType:
|
|
269
|
+
return GraphQLInputObjectType(entry.type_name + "OrderBy", {name: GraphQLInputField(SORT) for name in entry.props}
|
|
270
|
+
or {"id": GraphQLInputField(SORT)})
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
def _graphql_schema(model: Model) -> GraphQLSchema:
|
|
274
|
+
node_interface = GraphQLInterfaceType("Node", {"id": GraphQLField(GraphQLNonNull(GraphQLID))},
|
|
275
|
+
resolve_type=lambda obj, *_: obj["#typename"])
|
|
276
|
+
objects: Dict[str, GraphQLObjectType] = {}
|
|
277
|
+
wheres = {label: _where_type(e) for label, e in model.labels.items()}
|
|
278
|
+
orders = {label: _order_type(e) for label, e in model.labels.items()}
|
|
279
|
+
|
|
280
|
+
def list_args(label: str) -> Dict[str, GraphQLArgument]:
|
|
281
|
+
return {"where": GraphQLArgument(wheres[label]),
|
|
282
|
+
"orderBy": GraphQLArgument(GraphQLList(GraphQLNonNull(orders[label]))),
|
|
283
|
+
"first": GraphQLArgument(GraphQLInt), "offset": GraphQLArgument(GraphQLInt)}
|
|
284
|
+
|
|
285
|
+
edge_types: Dict[Tuple[str, str], GraphQLObjectType] = {}
|
|
286
|
+
|
|
287
|
+
def edge_type(rel: Rel) -> GraphQLObjectType:
|
|
288
|
+
"""One edge type per relationship type and the label at the edge's far end: KnowsEdgeToPerson."""
|
|
289
|
+
key = (rel.rel_type, rel.target)
|
|
290
|
+
if key not in edge_types:
|
|
291
|
+
camel = _camel(rel.rel_type)
|
|
292
|
+
name = f"{camel[0].upper()}{camel[1:]}EdgeTo{model.labels[rel.target].type_name}"
|
|
293
|
+
fields = {p.field: GraphQLField(p.scalar) for p in rel.props}
|
|
294
|
+
fields["node"] = GraphQLField(GraphQLNonNull(objects[model.labels[rel.target].type_name]))
|
|
295
|
+
edge_types[key] = GraphQLObjectType(name, fields)
|
|
296
|
+
return edge_types[key]
|
|
297
|
+
|
|
298
|
+
for label, entry in model.labels.items():
|
|
299
|
+
def fields(entry=entry):
|
|
300
|
+
out = {"id": GraphQLField(GraphQLNonNull(GraphQLID))}
|
|
301
|
+
for name, p in entry.props.items():
|
|
302
|
+
out[name] = GraphQLField(GraphQLNonNull(p.scalar) if p.required else p.scalar)
|
|
303
|
+
for fname, rel in entry.rels.items():
|
|
304
|
+
target = objects[model.labels[rel.target].type_name]
|
|
305
|
+
item = edge_type(rel) if fname == rel.edges_field else target
|
|
306
|
+
out[fname] = GraphQLField(GraphQLNonNull(GraphQLList(GraphQLNonNull(item))), args=list_args(rel.target))
|
|
307
|
+
return out
|
|
308
|
+
objects[entry.type_name] = GraphQLObjectType(entry.type_name, fields, interfaces=[node_interface],
|
|
309
|
+
is_type_of=lambda obj, _info, n=entry.type_name: obj["#typename"] == n)
|
|
310
|
+
query_fields = {e.root_field: GraphQLField(GraphQLNonNull(GraphQLList(GraphQLNonNull(objects[e.type_name]))),
|
|
311
|
+
args=list_args(label))
|
|
312
|
+
for label, e in model.labels.items()}
|
|
313
|
+
query_fields["node"] = GraphQLField(node_interface, args={"id": GraphQLArgument(GraphQLNonNull(GraphQLID))})
|
|
314
|
+
return GraphQLSchema(query=GraphQLObjectType("Query", query_fields), types=list(objects.values()))
|