Use the Python connector to run SQL and MongoQL (MQL) queries against Polypheny over Prism. The connector follows the Python DB-API and exposes SQL results as rows and document results as Python dictionaries. Python driver API
Install and connect
The examples use connector 2.0.0, Python 3.9 or later, and a Polypheny server with a Prism 2.2 interface. Install the connector in your Python environment. Connector release ยท Prism query interface
python -m pip install "polypheny==2.0.0"
Both examples connect over plain TCP and use the following defaults for a local Polypheny instance. Set these environment variables to connect to a different instance.
| Environment variable | Default |
|---|---|
POLYPHENY_HOST |
127.0.0.1 |
POLYPHENY_PORT |
20590 |
POLYPHENY_USER |
pa |
POLYPHENY_PASSWORD |
Empty string |
Insert and query relational data
Save this example as sql_example.py and run python sql_example.py. It creates a uniquely named table, binds Python values to SQL ? placeholders, and prints the two committed rows. A third insert is rolled back before the query.
import os
from contextlib import closing
from uuid import uuid4
import polypheny
address = (
os.getenv("POLYPHENY_HOST", "127.0.0.1"),
int(os.getenv("POLYPHENY_PORT", "20590")),
)
table = f"py_contacts_{uuid4().hex}"
with closing(polypheny.connect(
address,
username=os.getenv("POLYPHENY_USER", "pa"),
password=os.getenv("POLYPHENY_PASSWORD", ""),
transport="plain",
)) as connection, closing(connection.cursor()) as cursor:
cursor.execute(
f"CREATE TABLE {table} (id INTEGER PRIMARY KEY, name VARCHAR(80))"
)
try:
cursor.executemany(
f"INSERT INTO {table} (id, name) VALUES (?, ?)",
[(1, "Ada"), (2, "Grace")],
)
connection.commit()
cursor.execute(f"INSERT INTO {table} (id, name) VALUES (?, ?)", (3, "Katherine"))
connection.rollback()
cursor.execute(f"SELECT id, name FROM {table} WHERE id >= ? ORDER BY id", (1,))
print(cursor.fetchall())
finally:
connection.rollback()
cursor.execute(f"DROP TABLE {table}")
Polypheny commits DDL such as CREATE TABLE and DROP TABLE automatically. Commit or roll back your writes before issuing DDL so the transaction ends where you intend. Use placeholders for values and construct identifiers from trusted input, such as the UUID-generated suffix above.
Query documents with MongoQL
Save this example as document_example.py and run python document_example.py. Enable the MQL plugin and configure a store that supports document collections. The example creates a temporary document namespace, inserts one document, and reads it with executeany("mongo", ..., namespace=...). It prints the matching name from the returned dictionary.
import json
import os
from contextlib import closing
from uuid import uuid4
import polypheny
address = (
os.getenv("POLYPHENY_HOST", "127.0.0.1"),
int(os.getenv("POLYPHENY_PORT", "20590")),
)
namespace = f"py_docs_{uuid4().hex}"
with closing(polypheny.connect(
address,
username=os.getenv("POLYPHENY_USER", "pa"),
password=os.getenv("POLYPHENY_PASSWORD", ""),
transport="plain",
)) as connection, closing(connection.cursor()) as cursor:
cursor.execute(f"CREATE DOCUMENT NAMESPACE {namespace}")
try:
cursor.executeany("mongo", 'db.createCollection("contacts")', namespace=namespace)
document = {"_id": "example-contact", "name": "Ada"}
cursor.executeany(
"mongo",
f"db.contacts.insertOne({json.dumps(document)})",
namespace=namespace,
)
connection.commit()
cursor.executeany("mongo", 'db.contacts.find({"name":"Ada"})', namespace=namespace)
for contact in cursor.fetchall():
print(contact["name"])
finally:
connection.rollback()
cursor.execute(f"DROP NAMESPACE {namespace}")
See Document Collection Metadata to inspect field paths, an optional JSON sample, and indexes through Prism.
Map relational tables with PolyNOM
PolyNOM maps relational rows to Python model instances. Register a schema to describe a table, then use a session to add, query, and commit model instances. PolyNOM 0.4.0 requires Python 3.11 or later and installs a compatible 2.x connector as a dependency. PolyNOM 0.4.0 on PyPI
python -m pip install "polypheny-polynom==0.4.0"
The PolyNOM guide walks through a complete schema, model, and session example. PolyNOM guide
