Use the Polypheny .NET driver for SQL and MongoQL (MQL) queries and entity metadata over the Prism query interface. The driver uses ADO.NET types for connections, commands, transactions, and SQL data readers. See the C# integration guide for complete examples.
Versions and installation
The PolyphenyDotNetDriver NuGet package version 2.0.0 targets .NET 6 and can be used by later compatible .NET versions. It uses Prism 2.2 protocol bindings. The server must accept a Prism 2.x client, and returning document collection metadata requires server support introduced with Prism 2.2. See the NuGet package and GitHub release.
Run this command in an existing .NET project.
dotnet add package PolyphenyDotNetDriver --version 2.0.0
Import the PolyphenyDotNetDriver namespace. Entity metadata uses types from the transitive Polypheny.Prism package.
Connections and transactions
| API | Behavior |
|---|---|
PolyphenyDriver.OpenConnection(connectionString) |
Constructs a PolyphenyConnection with the default configuration. Call Open() or OpenAsync() to connect. |
new PolyphenyConnection(connectionString, config) |
Constructs a connection with explicit PolyphenyConfig. The Database and DataSource values are labels. The transport version defaults to plain-v1@polypheny.com\n. |
Open() and OpenAsync(cancellationToken) |
Connect and negotiate the transport and Prism protocol. |
State and Ping() |
Report the local connection state and send a connection check, respectively. |
CreateCommand() |
Creates an ADO.NET command associated with the connection. For a typed PolyphenyCommand, use the fluent constructor shown in the integration guide. |
BeginTransaction() |
Creates a transaction handle. The Prism session has auto-commit disabled. |
Commit() and CommitAsync(cancellationToken) |
Commit pending writes on the connection. |
Rollback() and RollbackAsync(cancellationToken) |
Discard pending writes on the connection. |
Close(), CloseAsync(), and Dispose() |
Close the connection. Close() and CloseAsync() send a Prism disconnect request when the connection is open. |
The connection string is host:port,user:password. The parser uses commas and colons as delimiters and supports DNS names and IPv4 addresses. For a local Prism interface with its default port and credentials, use localhost:20590,pa:. To select a namespace, qualify SQL entity names, or pass the namespace explicitly for MQL and metadata. Complete one operation before starting another on the same connection.
Commands and results
| API | Behavior |
|---|---|
WithConnection(connection), WithCommandText(text) |
Associate a newly constructed command with a connection and set its statement text. |
WithTransaction(transaction) |
Associate a command with a transaction from the same connection. |
WithParameterValues(values), Prepare(), PrepareAsync(cancellationToken) |
Supply values for positional SQL ? placeholders and prepare the command for ExecuteNonQuery(). Bind values in placeholder order. |
ExecuteNonQuery() and ExecuteNonQueryAsync(cancellationToken) |
Run SQL that returns a scalar update count, including data and schema writes. |
ExecuteReader() and ExecuteReaderAsync() |
Run unparameterized SQL and read relational rows. The synchronous method returns a PolyphenyDataReader, and the asynchronous ADO.NET method returns a DbDataReader. |
ExecuteQueryMongo(namespaceName) |
Run a MongoQL query that returns a document result. The parameterless overload uses the server’s default namespace. |
Use Read() or ReadAsync() to move through SQL rows. Access columns by zero-based ordinal or by name, and use IsDBNull() before reading a nullable column with a typed getter. FieldCount, GetName(), and GetOrdinal() expose the available columns. The reader and the document query method materialize the first result frame in version 2.0.0.
Positional SQL parameters accept int, long, float, double, string, and bool. The same value types can be read from SQL and MQL results. Document keys are strings in a Dictionary<object, object>, lists are object[], and Prism null values are C# null.
ExecuteScalar(), Cancel(), and ChangeDatabase() throw NotImplementedException. Isolation levels and command timeouts are currently not applied to the Prism request. Support for asynchronous execution and cancellation varies by method.
Entity metadata
Call SearchEntities(namespaceName, entityPattern) or SearchEntitiesAsync(namespaceName, entityPattern) on an open connection. Both return an IReadOnlyList<Polypheny.Prism.Entity>. Omit the optional second argument to list the namespace. The server applies the pattern if you supply it.
Relational entries expose Entity.Table. Document collection entries expose Entity.Document with the following properties.
| Property | Meaning |
|---|---|
NamespaceName, CollectionName |
Identify the collection. |
Fields |
Each DocumentField has a FieldPath, TypeName, and IsOptional. Paths can identify nested keys using dots, and optional fields may be absent or null. Field information can be inferred from sampled documents. |
HasSampleDocumentJson, SampleDocumentJson |
Indicate whether a sample was returned and hold its JSON text. Check presence before reading the sample. |
DocumentIndexes |
Each DocumentIndex reports FieldPath, IndexType, and Unique. The collection and storage adapter determine which indexes are available. |
See the Prism document metadata reference for the underlying messages.
