Prism is the binary query interface for Polypheny-DB. A driver opens a session over TCP or a Unix domain socket, sends queries and metadata requests, and receives results as Protocol Buffer messages.
What you can do
| Task | What Prism provides |
|---|---|
| Run SQL, MongoQL, or Cypher | Choose the language and optionally the namespace for a statement. |
| Read and change data | Receive tabular rows, documents, graph elements, or a scalar result such as an update count. Fetch large results in pages. |
| Reuse statements | Prepare parameterized SQL statements and execute supported operations in batches. |
| Control transactions | Use auto-commit or explicitly commit and roll back work in a session. |
| Inspect the catalog | List namespaces and their entities. With Prism 2.2 or later, inspect observed fields, a sample document when available, and reported indexes for document collections. |
Drivers expose the operations and result types they support. Check the driver documentation for its supported query languages, transports, and data types.
Connect a driver
Choose a driver that supports the Prism major version and features of your Polypheny-DB server.
TCP
- Open Interfaces in the Polypheny-DB web UI. Enable Prism Interface (Plain transport) if there is no TCP listener.
- Configure the driver with the server’s address and the listener’s port. For a local installation, the default endpoint is
127.0.0.1:20590. For a container, connect to the published host port. - Supply a Polypheny-DB username and password. A fresh local installation has a
paaccount with an empty password.
The TCP listener binds to all IPv4 interfaces in the server’s network environment. Plain TCP carries credentials and query data without encryption. Limit access to the intended hosts and use an encrypted tunnel if the connection crosses an untrusted network.
Unix domain socket
Enable Prism Interface (Unix transport) in Interfaces and point a compatible local driver to the configured socket. The path must end in .sock. You can set an absolute path or a relative filename. A relative filename such as the default polypheny-prism.sock resolves in the server’s data directory. The server log shows the bound path.
Depending on the driver, authenticate with explicit credentials or have the server look up a database user from the peer’s operating system identity.
Protocol compatibility
Polypheny-DB checks the Prism API major version when the client connects and reports its own major and minor version. Features introduced in minor releases can require support from both peers even after a successful connection.
| Version | Feature or compatibility boundary |
|---|---|
| Prism 1.9 | The version used by Polypheny-DB 0.10.1. Use a driver compatible with Prism 1.x. |
| Prism 2.2 | Adds collection metadata to the entity listing response. The client needs bindings or driver support for the new fields. |
| Prism 2.3 | Adds graph values to tabular results. To preserve columns in a mixed graph and scalar projection, use a client that advertises 2.3 or later in the 2.x series and can decode the graph values. |
Troubleshoot a connection
| Symptom | What to check |
|---|---|
| Connection refused or timed out | Confirm the interface is running. Check the host, port, network access, and container port mapping. |
| Authentication fails | Check the Polypheny-DB credentials or, for Unix sockets, the operating system account mapped by the server. |
| The server reports an incompatible API version | Check the server’s Prism major version and choose a matching driver. |
| A feature is missing after connecting | Check the server and driver support for that feature, including the Prism minor version. |
Read on
- Follow the developer guide to build a Prism client and execute a paginated query.
- Use the examples to inspect document collection metadata or decode Cypher results.
- Look up request names, result formats, and value encodings in the protocol reference.
Acknowledgments
Tobias Hafner developed the initial Prism interface as part of his bachelor’s thesis at the University of Basel.