Proto Interface - Protocol Description

In our gRPC architecture, the Protocol Buffer (protobuf) messages defining the interface of our services are meticulously structured for better organization and clarity. Instead of housing all messages within a single .proto file, they are categorized based on functionality or domain.

For each such category, two distinct files are maintained:

• Requests: This file encompasses all the protobuf message definitions that pertain to requests made from clients to the server. By convention, the filename for this category always concludes with _requests.proto. For example, if we’re handling user-related data, the request messages might be contained within a file named user_requests.proto.

• Responses: In tandem with our request definitions, every category also maintains a file that specifically contains messages related to the responses returned by the server to the client. This file is identified by its suffix _responses.proto. Following our earlier example, response messages related to user operations would be located in `user_responses.proto.

This separation ensures a clean demarcation between the request and response message definitions, making it straightforward for developers to locate, update, or extend the RPC message definitions based on their nature and purpose.

In our gRPC system architecture, there’s a distinct file named protointerface.proto that plays a pivotal role. This file is dedicated to consolidating all the remote procedure calls (RPCs) that our proto interface supports. By centralizing the definitions of the RPCs in protointerface.proto, we ensure a clear and easily accessible overview of all the available service methods, separate from the categorized request and response message definitions.

Message categories

The table below contains the available categories of messages and the explicit names of their .proto files.

Remote Procedure calls

This chapter outlines the remote procedure calls (RPCs) available within the proto interface. Readers will gain insight into the service methods and the corresponding request and response structures. A vrief overview aove all calls is given in the table below.

CheckConnection

The CheckConnection procedure is utilized to verify the state of an established connection to the server. It allows clients to ensure that the connection is still active and in good health.

Input Message:

• Message Name: ConnectionCheckRequest
• Contained in File: connection_requests.proto

Return Message:

• Message Name: ConnectionCheckResponse
• Contained in File: connection_responses.proto

Signature:

rpc CheckConnection(ConnectionCheckRequest) returns (ConnectionCheckResponse) {}

CloseStatement

The CloseStatement procedure is used to formally close a previously prepared or executed database statement. Closing a statement releases the resources associated with it and ensures that there are no lingering locks or allocations.

Input Message:

• Message Name: CloseStatementRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: CloseStatementResponse
• Contained in File: statement_responses.proto

Signature:

rpc CloseStatement(CloseStatementRequest) returns (CloseStatementResponse) {}

CommitTransaction

The CommitTransaction procedure is utilized to commit the changes made during a database transaction. Committing ensures that all the modifications made during the transaction are permanently saved in the database. If any error occurs during the commit, the changes can be rolled back to maintain the database’s consistency.

Input Message:

• Message Name: CommitRequest
• Contained in File: transaction_requests.proto

Return Message:

• Message Name: CommitResponse
• Contained in File: transaction_responses.proto

Signature:

rpc CommitTransaction(CommitRequest) returns (CommitResponse) {}

Connect

The Connect procedure is designed to establish a connection to the database. Once connected, clients can perform various operations like executing queries, fetching results, or managing transactions. This procedure serves as the initial entry point for interactions between the client and the database.

Input Message:

• Message Name: ConnectionRequest
• Contained in File: connection_requests.proto

Return Message:

• Message Name: ConnectionResponse
• Contained in File: connection_responses.proto

Signature:

rpc Connect(ConnectionRequest) returns (ConnectionResponse) {}

Disconnect

The Disconnect procedure is utilized to safely terminate an existing connection to the database. Disconnecting ensures that any pending transactions or uncommitted changes are dealt with appropriately, and resources associated with the connection are released.

Input Message:

• Message Name: DisconnectRequest
• Contained in File: connection_requests.proto

Return Message:

• Message Name: DisconnectionResponse
• Contained in File: connection_responses.proto

Signature:

rpc Disconnect(DisconnectRequest) returns (DisconnectionResponse) {}

ExecuteIndexedStatement

The ExecuteIndexedStatement procedure is designed to execute a provided indexed statement in the database. An indexed statement contains placeholders, where values can be assigned based on their order, rather than by specific placeholder names.

Input Message:

• Message Name: ExecuteIndexedStatementRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: StatementResult
• Contained in File: statement_responses.proto

Signature:

rpc ExecuteIndexedStatement(ExecuteIndexedStatementRequest) returns (StatementResult) {}

ExecuteIndexedStatementBatch

The ExecuteIndexedStatementBatch procedure allows for the execution of a batch of indexed statements. These indexed statements contain placeholders where values are assigned based on their order in the statement. By processing these statements in batches, clients can optimize database interactions and potentially achieve better performance, especially when dealing with large amounts of data.

Input Message:

• Message Name: ExecuteIndexedStatementBatchRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: StatementBatchResponse
• Contained in File: statement_responses.proto

Signature:

rpc ExecuteIndexedStatementBatch(ExecuteIndexedStatementBatchRequest) returns (StatementBatchResponse) {}

ExecuteNamedStatement

The ExecuteNamedStatement procedure facilitates the execution of a previously prepared named statement in the database. Named statements are database queries with named placeholders, providing clarity when assigning values to the statement.

Input Message:

• Message Name: ExecuteNamedStatementRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: StatementResult
• Contained in File: statement_responses.proto

Signature:

rpc ExecuteNamedStatement(ExecuteNamedStatementRequest) returns (StatementResult) {}

ExecuteUnparameterizedStatement

The ExecuteUnparameterizedStatement procedure is employed to execute a database statement that does not contain any parameters or placeholders. This straightforward approach ensures a direct interaction with the database without any variable assignments.

Input Message:

• Message Name: ExecuteUnparameterizedStatementRequest
• Contained in File: statement_requests.proto

Return Message (stream):

• Message Name: StatementResponse
• Contained in File: statement_responses.proto

Signature:

rpc ExecuteUnparameterizedStatement(ExecuteUnparameterizedStatementRequest) returns (stream StatementResponse) {}

The ExecuteUnparameterizedStatement call is a server streaming RPC. When invoked, it returns two StatementResponse messages in sequence:

1. The first StatementResponse provides the statement ID of the executed statement, serving as a unique identifier.
2. The second StatementResponse delivers both the same statement ID and the initial frame of the result, allowing clients to commence with data processing or further fetch operations.

ExecuteUnparameterizedStatementBatch

The ExecuteUnparameterizedStatementBatch procedure allows for the execution of a batch of unparameterized database statements. These are statements that do not require any dynamic placeholders or parameters. The use of server streaming in the response indicates that the server can send back multiple StatementBatchResponse messages to the client within a single call, ideal for processing large batches or sets of results.

Input Message:

• Message Name: ExecuteUnparameterizedStatementBatchRequest
• Contained in File: statement_requests.proto

Return Message (stream):

• Message Name: StatementBatchResponse
• Contained in File: statement_responses.proto

Signature:

rpc ExecuteUnparameterizedStatementBatch(ExecuteUnparameterizedStatementBatchRequest) returns (stream StatementBatchResponse) {}

The ExecuteUnparameterizedStatementBatch call is a server streaming RPC. When invoked, it returns two StatementBatchResponse messages in sequence:

1. The first StatementBatchResponse provides the statement ID of the statement batch, serving as a unique identifier.
2. The second StatementResponse delivers both the same statement ID and a list of update counts of the individual statements.

FetchResult

The FetchResult procedure is employed to retrieve the result frames of previously executed statements.This RPC allows to sequentially fetch the associated result frames from the database. This is useful for statements that produce large results, enabling the client to retrieve data in manageable portions rather than all at once.

Input Message:

• Message Name: FetchRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: Frame
• Contained in File: statement_responses.proto

Signature:

rpc FetchResult(FetchRequest) returns (Frame) {}

GetClientInfoProperties

The GetClientInfoProperties procedure retrieves the client-specific client properties stored on the database. These properties consist of a set of arbitrary key-value pairs set by the client and can be used to stor additional information about a client.

Input Message:

• Message Name: ClientInfoPropertiesRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: ClientInfoProperties
• Contained in File: meta_responses.proto

Signature:

rpc GetClientInfoProperties(ClientInfoPropertiesRequest) returns (ClientInfoProperties) {}

GetClientInfoPropertyMetas

The GetClientInfoPropertyMetas procedure retrieves metadata about the client properties stored on the database. This metadata provides insights into the structure, constraints, and possible values of the client properties, aiding in understanding and correctly setting client-specific information.

Input Message:

• Message Name: ClientInfoPropertyMetaRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: ClientInfoPropertyMetaResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetClientInfoPropertyMetas(ClientInfoPropertyMetaRequest) returns (ClientInfoPropertyMetaResponse) {}

GetDatabases

The GetDatabases procedure is designed to fetch a list of databases that are present in the system. By invoking this RPC, clients can receive an overview of all available databases, enabling them to choose a specific database for operations or understand the data landscape of the connected environment.

Input Message:

• Message Name: DatabasesRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: DatabasesResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetDatabases(DatabasesRequest) returns (DatabasesResponse) {}

GetDbmsVersion

The GetDbmsVersion procedure provides a means to retrieve the version details of the Database Management System (DBMS) in use.

Input Message:

• Message Name: DbmsVersionRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: DbmsVersionResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetDbmsVersion(DbmsVersionRequest) returns (DbmsVersionResponse) {}

GetNamespace

The GetNamespace procedure is specifically designed to retrieve metadata about a particular namespace specified in the NamespaceRequest.

Input Message:

• Message Name: NamespaceRequest
• Contained in File: namespace_meta_requests.proto

Return Message:

• Message Name: Namespace
• Contained in File: namespace_meta_responses.proto

Signature:

rpc GetNamespace(NamespaceRequest) returns (Namespace) {}

GetSqlKeywords

The GetSqlKeywords procedure is used for retrieving a list of SQL keywords supported by the DBMS.

Input Message:

• Message Name: SqlKeywordsRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: MetaStringResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetSqlKeywords(SqlKeywordsRequest) returns (MetaStringResponse) {}

GetSqlNumericFunctions

The GetSqlNumericFunctions procedure is designed to fetch a list of SQL numeric functions that the DBMS supports.

Input Message:

• Message Name: SqlNumericFunctionsRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: MetaStringResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetSqlNumericFunctions(SqlNumericFunctionsRequest) returns (MetaStringResponse) {}

GetSqlStringFunctions

The GetSqlStringFunctions procedure is used to retrieve a list of SQL string functions supported by the DBMS.

Input Message:

• Message Name: SqlStringFunctionsRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: MetaStringResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetSqlStringFunctions(SqlStringFunctionsRequest) returns (MetaStringResponse) {}

GetSqlSystemFunctions

The GetSqlSystemFunctions procedure is engineered to obtain a list of SQL system functions that the DBMS supports.

Input Message:

• Message Name: SqlSystemFunctionsRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: MetaStringResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetSqlSystemFunctions(SqlSystemFunctionsRequest) returns (MetaStringResponse) {}

GetSqlTimeDateFunctions

The GetSqlTimeDateFunctions procedure is dedicated to fetching a list of SQL time and date functions that the DBMS supports.

Input Message:

• Message Name: SqlTimeDateFunctionsRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: MetaStringResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetSqlTimeDateFunctions(SqlTimeDateFunctionsRequest) returns (MetaStringResponse) {}

GetSupportedLanguages

The GetSupportedLanguages procedure is geared towards retrieving a list of query languages that the DBMS supports for statements.

Input Message:

• Message Name: LanguageRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: LanguageResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetSupportedLanguages(LanguageRequest) returns (LanguageResponse) {}

GetTableTypes

The GetTableTypes procedure is specifically crafted to retrieve a list of table types that the DBMS supports.

Input Message:

• Message Name: TableTypesRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: TableTypesResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetTableTypes(TableTypesRequest) returns (TableTypesResponse) {}

GetTypes

The GetTypes procedure aims to fetch a list of data types supported by the DBMS.

Input Message:

• Message Name: TypesRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: TypesResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetTypes(TypesRequest) returns (TypesResponse) {}

GetUserDefinedTypes

The GetUserDefinedTypes procedure is constructed to retrieve a list of user-defined data types present in the DBMS.

Input Message:

• Message Name: UserDefinedTypesRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: UserDefinedTypesResponse
• Contained in File: meta_responses.proto

Signature:

rpc GetUserDefinedTypes(UserDefinedTypesRequest) returns (UserDefinedTypesResponse) {}

PrepareIndexedStatement

The PrepareIndexedStatement procedure is designed to prepare a statement containing placeholders based on their order, referred to as an indexed statement. The PreparedStatementSignature returned by this call contains metadata for ablut the values permitted for each placeholder.

Input Message:

• Message Name: PrepareStatementRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: PreparedStatementSignature
• Contained in File: statement_responses.proto

Signature:

rpc PrepareIndexedStatement(PrepareStatementRequest) returns (PreparedStatementSignature) {}

PrepareNamedStatement

The PrepareNamedStatement procedure is used to prepare a database statement that uses named placeholders for variable values. Named statements provide a mechanism to identify variables by a specific name, making it easier to assign values without relying solely on the order of appearance. he PreparedStatementSignature returned by this call contains metadata for ablut the values permitted for each placeholder.

Input Message:

• Message Name: PrepareStatementRequest
• Contained in File: statement_requests.proto

Return Message:

• Message Name: PreparedStatementSignature
• Contained in File: statement_responses.proto

Signature:

rpc PrepareNamedStatement(PrepareStatementRequest) returns (PreparedStatementSignature) {}

RollbackTransaction

The RollbackTransaction procedure provides the functionality to revert any changes made within the current transaction, ensuring data integrity and consistency.

Input Message:

• Message Name: RollbackRequest
• Contained in File: transaction_requests.proto

Return Message:

• Message Name: RollbackResponse
• Contained in File: transaction_responses.proto

Signature:

rpc RollbackTransaction(RollbackRequest) returns (RollbackResponse) {}

SearchEntities

The SearchEntities procedure allows clients to retrieve metadata about specific entities within a specific namespace. Entities can refer to tables, documents or graphs.

Input Message:

• Message Name: EntitiesRequest
• Contained in File: namespace_meta_requests.proto

Return Message:

• Message Name: EntitiesResponse
• Contained in File: namespace_meta_responses.proto

Signature:

rpc SearchEntities(EntitiesRequest) returns (EntitiesResponse) {}

SearchFunctions

The SearchFunctions procedure facilitates clients in searching for and retrieving metadata of specific functions available within the DBMS. Functions could be built-in, user-defined, or any other supported categories. This RPC allows users to locate and get details of functions based on certain criteria.

Input Message:

• Message Name: FunctionsRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: FunctionsResponse
• Contained in File: meta_responses.proto

Signature:

rpc SearchFunctions(FunctionsRequest) returns (FunctionsResponse) {}

SearchNamespaces

The SearchNamespaces procedure is designed to allow clients to retrieve a list of metadata related to the namespaces within the DBMS.

Input Message:

• Message Name: NamespacesRequest
• Contained in File: namespace_meta_requests.proto

Return Message:

• Message Name: NamespacesResponse
• Contained in File: namespace_meta_responses.proto

Signature:

rpc SearchNamespaces(NamespacesRequest) returns (NamespacesResponse) {}

SearchProcedures

The SearchProcedures procedure enables clients to search for and retrieve metadata about specific stored procedures available within the DBMS.

Input Message:

• Message Name: ProceduresRequest
• Contained in File: meta_requests.proto

Return Message:

• Message Name: ProceduresResponse
• Contained in File: meta_responses.proto

Signature:

rpc SearchProcedures(ProceduresRequest) returns (ProceduresResponse) {}

SetClientInfoProperties

The SetClientInfoProperties procedure facilitates clients in setting or updating key-value pairs known as client info properties on the database. These properties provide additional information about a connected client, aiding in tasks such as monitoring, auditing, and debugging.

Input Message:

• Message Name: ClientInfoProperties
• Contained in File: meta_requests.proto

Return Message:

• Message Name: ClientInfoPropertiesResponse
• Contained in File: meta_responses.proto

Signature:

rpc SetClientInfoProperties(ClientInfoProperties) returns (ClientInfoPropertiesResponse) {}

UpdateConnectionProperties

The UpdateConnectionProperties procedure is utilized by clients to update various properties related to a connection.

Input Message:

• Message Name: ConnectionPropertiesUpdateRequest
• Contained in File: connection_requests.proto

Return Message:

• Message Name: ConnectionPropertiesUpdateResponse
• Contained in File: connection_responses.proto

Signature:

rpc UpdateConnectionProperties(ConnectionPropertiesUpdateRequest) returns (ConnectionPropertiesUpdateResponse) {}

Protocol Messages

This section provides a comprehensive breakdown of protocol messages used in the communication between clients and the server. The messages are categorized into distinct groups, each representing a specific aspect of the interaction. Starting from connection-related messages and extending to transaction handling and beyond, the documentation delves into the purpose, structure, and usage of each message.

Connection Messages

The following section provides information about all messages related to a client’s connection and it’s properties.

ConnectionRequest

The ConnectionRequest message is designed to initiate a connection request from the client to the server. It contains information regarding the API version, client identity, and optional credentials, as well as properties associated with the connection.

When no username is specified the default user of the database is chosen. The absence of a password is used to specify that the selected user does not require a password to authenticate. If no connection properties are specified a set of default properties is used. If connection properties are specified that have unset fields default values are used for those.

ConnectionProperties

The ConnectionProperties message defines specific properties related to the client-server connection. It allows clients to specify certain behaviors and settings for the connection, such as transaction auto-commit status and target namespace preference.

Absent values are either ignored or replaced with default values depending on the context or remote procedure. See the coresponding documentations for reference.

ConnectionPropertiesUpdateRequest

The ConnectionPropertiesUpdateRequest message allows clients to update the properties associated with their connection. This request enables dynamic modification of connection behavior without necessitating a re-establishment of the connection.

When the specified connection properties miss some of the parameters only the paramers containing a value are updated.

ConnectionCheckRequest

The ConnectionCheckRequest message in combination with the corresponding remot procedure call is utilized to verify the current state of an established connection. It acts as a simple “ping” request, enabling clients to ascertain if the server is responsive and if the connection is still valid.

DisconnectRequest

The DisconnectRequest message, when paired with its respective remote procedure call, signals the intent to terminate an established connection. It serves as a formal request from the client to disconnect from the server, ensuring a graceful termination process.

ConnectionResponse

The ConnectionResponse message is sent by the server in response to a ConnectionRequest from the client. It provides feedback regarding the compatibility of the client’s API version with the server, as well as other important information about the connection.

DisconnectionResponse

The DisconnectionResponse message is sent by the server in response to a DisconnectRequest from the client. It provides an acknowledgment that the disconnection process has been acknowledged and processed by the server.

ConnectionCheckResponse

The ConnectionCheckResponse message is sent by the server in response to a ConnectionCheckRequest from the client. It acts as an affirmation that the server is responsive, and the connection is still valid.

ConnectionPropertiesUpdateResponse

The ConnectionPropertiesUpdateResponse message is sent by the server in response to a ConnectionPropertiesUpdateRequest from the client. It acknowledges the success of the requested connection properties update.

Document Frame Messages

This section describes all messages required to represent a frame of a result in the document model.

DocumentFrame

The DocumentFrame message represents a frame containing one or more documents and is used to relay results or data entries structured as documents from the server to the client.

Error Messages

This section describes all messages required to represent an exception.

ErrorDetails

The ErrorDetails message conveys specific information about an error encountered during the processing of a request. This detailed feedback aids clients in understanding the nature and cause of an issue.

Graph Frame Messages

This section describes all messages required to represent a frame of a result in the graph model.

GraphFrame

The GraphFrame message is a placeholder intended to represent graph frames as part of the labeled property graph model. As of now, the graph model is not fully implemented, making this message void of fields. It acts as a provision for future developments where fields related to the graph model will be added.

Meta Messages

Messages that are used for querying general metadata.

DbmsVersionRequest

The DbmsVersionRequest message is utilized to request the version information of the database management system (DBMS) in use. It acts as a trigger for the server to respond with the specific version details of the DBMS.

LanguageRequest

The LanguageRequest message facilitates the retrieval of supported query languages that can be used for constructing statements.

DatabasesRequest

The DatabasesRequest message is employed to solicit a list of databases that are currently managed by the DBMS. This is pivotal for clients aiming to interact with a specific database or to understand the landscape of databases under management.

TableTypesRequest

The TableTypesRequest message is designed to request information about the different types of tables that are supported or recognized by the DBMS.

TypesRequest

The TypesRequest message is deployed to obtain a list of data types supported by the database management system. This helps clients understand the range of data types they can utilize when defining or querying tables.

UserDefinedTypesRequest

The UserDefinedTypesRequest message facilitates the retrieval of user-defined data types present in the database. These custom data types can be crafted to meet specific needs not met by standard types.

SqlStringFunctionsRequest

The SqlStringFunctionsRequest message is used to solicit information about the string functions supported by the SQL implementation of the DBMS.

SqlSystemFunctionsRequest

The SqlSystemFunctionsRequest message aims to retrieve the list of system functions provided by the SQL implementation of the DBMS.

SqlTimeDateFunctionsRequest

The SqlTimeDateFunctionsRequest message is dispatched to fetch a list of time and date functions supported by the SQL implementation of the DBMS.

SqlNumericFunctionsRequest

The SqlNumericFunctionsRequest message endeavors to obtain details about the numeric functions provided by the SQL implementation of the DBMS.

SqlKeywordsRequest

The SqlKeywordsRequest message is designed to request a list of reserved keywords utilized by the SQL implementation of the DBMS.

ProceduresRequest

The ProceduresRequest message is employed to retrieve a list of stored procedures in the database for a specified query language. The client can also narrow down the results by specifying a procedure name pattern.

ClientInfoPropertiesRequest

The ClientInfoPropertiesRequest message facilitates the acquisition of client information properties stored in the database. These properties can offer additional context about the connected client.

ClientInfoPropertyMetaRequest

The ClientInfoPropertyMetaRequest message aids in extracting metadata about the client information properties present in the database.

FunctionsRequest

The FunctionsRequest message is wielded to obtain a list of functions from the database based on the specified query language and function category.

DbmsVersionResponse

The DbmsVersionResponse message relays details about the version and name of the database management system (DBMS) in response to a DbmsVersionRequest.

LanguageResponse

The LanguageResponse message offers a list of query languages supported by the system.

DatabasesResponse

The DatabasesResponse message provides details about the databases present in the system.

Database

The Database message encapsulates details about an individual database.

TableTypesResponse

The TableTypesResponse message conveys information about the various table types present in the system.

TableType

The TableType message delineates the nature or category of a table.

TypesResponse

The TypesResponse message provides a list of native data types supported by the system.

Type

The Type message describes the characteristics and specifications of a particular native data type.

UserDefinedTypesResponse

The UserDefinedTypesResponse message offers a list of user-defined data types present in the system.

UserDefinedType

The UserDefinedType message encapsulates details about a specific user-defined data type.

ValueMeta

The ValueMeta message offers insights into the metadata of a specific fieldrelated to a user-defined type.

MetaStringResponse

The MetaStringResponse message encapsulates a string that represents some specific metadata information.

ProceduresResponse

The ProceduresResponse message provides a list of stored procedures available within the system.

Procedure

The Procedure message encapsulates details about a specific stored procedure in the system.

ReturnType Enum

The reuturn type enum is part of the message Procedure and indicates the possible types of return values for a stored procedure.

ClientInfoProperties

The ClientInfoProperties message encapsulates key-value pairs representing client-specific information.

ClientInfoPropertyMetaResponse

The ClientInfoPropertyMetaResponse message provides metadata about various client-specific properties.

ClientInfoPropertyMeta

The ClientInfoPropertyMeta message encapsulates metadata about a specific client property.

FunctionsResponse

The FunctionsResponse message provides a list of functions available within the system.

Function

The Function message encapsulates details about a specific function in the system.

Namespace Meta Messages

This section contains all messages related describing the metadata of namespaces and their entities.

NamespaceRequest

The NamespaceRequest message is designed for querying specific details about aspecific namespace.

NamespacesRequest

The NamespacesRequest message allows querying for namespaces based on specific patterns in their names as well as their types.

EntitiesRequest

The EntitiesRequest message is meant for querying details about entities within a specific namespace, possibly using a pattern to narrow down the results.

NamespacesResponse

The NamespacesResponse message delivers a list of namespaces based on the provided criteria in the NamespacesRequest.

EntitiesResponse

The EntitiesResponse message returns a list of entities that match the provided criteria from the EntitiesRequest.

Namespace

The Namespace message provides detailed information about a specific namespace.

Entity

The Entity message encapsulates different types of entities. Only one of the entities can be set for a given message instance.

Table

The Table message provides comprehensive information about a specific table within a database.

Column

The Column message describes the attributes of a specific column within a table.

PrimaryKey

The PrimaryKey message provides details about a table’s primary key.

ForeignKey

The ForeignKey message details a foreign key relationship between tables.

Index

The Index message provides details about an index defined on a table.

Graph

The Graph message will be used to represent the metadata of a graph entity. As of now, the structure is empty but it is expected to encapsulate various attributes and details about graph entities in the future.

Document

The Document message will be used to encapsulate the metadata related to a document entity. The structure is presently empty, but it’s expected to be expanded with attributes pertinent to documents in future updates.

Relational Frame Messages

Messages related to relational frames as used to represent the results from the relational model.

RelationalFrame

The RelationalFrame message encapsulates the structure of a relational frame, which includes metadata about columns and rows of data within a relational table.

ColumnMeta

The ColumnMeta message holds metadata related to a specific column within a relational table.

FieldMeta

The FieldMeta message provides metadata for individual fields, which can be part of complex structures like arrays or structs.

TypeMeta

The TypeMeta message is a comprehensive descriptor for the data types used within the system. This message not only defines simple data types but also accommodates complex types such as structures and arrays. Its flexibility allows it to describe a wide range of data types and data structures.

StructMeta

The StructMeta message provides metadata specific to structured types, giving details about the fields that make up the structure.

ArrayMeta

The ArrayMeta message provides metadata about array types, detailing the kind of elements they can hold.

Row

The Row message represents a single row within a relational frame.

Statement Messages

Messages related to statements in a query language and their results.

ExecuteUnparameterizedStatementRequest

Represents a request to execute a statement without any parameters.

If no fetch siz eis specified, a default value is used. If no namespace name is specified the namespace specified for the connection is used.

ExecuteUnparameterizedStatementBatchRequest

Encapsulates a batch of unparameterized statements to be executed.

PrepareStatementRequest

Represents a request to prepare a statement for execution.

ExecuteIndexedStatementRequest

Represents a request to execute a previously prepared statement by its ID, using indexed parameters.

ExecuteIndexedStatementBatchRequest

Encapsulates a batch request to execute a prepared statement multiple times with different sets of indexed parameters.

ExecuteNamedStatementRequest

Represents a request to execute a previously prepared statement by its ID, using named parameters.

IndexedParameters

Encapsulates indexed parameters for a prepared statement.

NamedParameters

Encapsulates named parameters for a prepared statement.

CloseStatementRequest

Represents a request to close a statement.

FetchRequest

Represents a request to fetch a batch of results for a previously executed statement.

If no fetch size is specified a default value is used.

StatementResponse

Represents the response after executing a statement.

StatementResult

Encapsulates the result of an executed statement.

StatementBatchResponse

Represents the response after executing a batch of statements.

PreparedStatementSignature

Provides metadata about a prepared statement, including its parameters.

ParameterMeta

Provides metadata about a single parameter of a prepared statement.

CloseStatementResponse

Represents the response after closing a prepared statement. The message is currently empty, indicating a simple acknowledgment of the action.

Frame

Represents a frame of data that could be one of several types.

This structure offers flexibility in representing different types of data responses, allowing for a more generic interface that can handle various data structures.

Transaction Messages

This section describes the messages involved in handling transactions.

CommitRequest

Represents a request to commit a transaction.

RollbackRequest

Represents a request to rollback a transaction.

CommitResponse

Represents the response after attempting to commit a transaction.

RollbackResponse

Represents the response after attempting to rollback a transaction.

Value Messages

Messages used to represent the types and values of the polypheny proprietary type system.

ProtoValue:

This message represents a single value supported by the DBMS. It acts as a container bundling the representation of a value together with it’s type.

Available ProtoValueType values:

Values available in the oneof value:

This structure provides a versatile way to store and transmit various types of values. The use of the oneof keyword ensures that only one datatype is set at a given time.

ProtoBoolean

Represents a boolean value.

ProtoInteger

Represents a 32-bit integer value.

ProtoLong

Represents a 64-bit long integer value.

ProtoBinary

Represents a binary data.

ProtoDate

Represents a date as a 64-bit integer.

ProtoDouble

Represents a double precision floating point number.

ProtoFloat

Represents a single precision floating point number.

ProtoNull

Represents a null value. This message doesn’t contain any fields.

ProtoString

Represents a string value.

ProtoTime

Represents a time value with a specified unit of time.

TimeUnit

Enumerates possible units of time.

ProtoTimeStamp

Represents a timestamp value.

ProtoBigDecimal

Represents a BigDecimal value with specified precision and scale.

ProtoStructured

Represents a structured data type comprising multiple ProtoValue fields.

ProtoInterval

Represents an interval value using a BigDecimal.

ProtoUserDefinedType

Defines a user-defined type with a specified template and value.

ProtoFile

Represents a file in byte format.

ProtoList

Represents a list of ProtoValue items.

ProtoMap

Represents a map of ProtoEntry items.

ProtoEntry

Defines a key-value pair using ProtoValue for both key and value.

ProtoDocument

Represents a document consisting of multiple ProtoEntry items.

ProtoEdge

Represents an edge in a graph.

ProtoNode

Represents a node in a graph.

ProtoGraph

Represents a graph entity with nodes and edges.

ProtoPath

Represents a path through nodes and edges in a graph.

ProtoSegment

Represents a segment within a path in a graph.

ProtoGraphPropertyHolder

Holds properties and labels for graph elements.

ProtoRowId

Represents the row identifier.

Metadata

The ProtoInterface uses the function of gRPC to send additional values as part of the header together with the remote procedure calls. This is used from the client to the server to send the clientUUID with each call, so that calls can be linked to a client. On the way back from the server to the client the header is used in case of an error to transmit additional info. For this the following two context keys are used which must be used to add the respective data to the header or to read it.

ClientUUID

Key name: clientUUID Type: Metadata.ASCII_STRING_MARSHALLER

A custom ClientInterceptor implemenation can be used to add the clientUUID to a call. An example of such an implementation is provided below:

public class ClientMetaInterceptor implements ClientInterceptor {
    private final String clientUUID;

    public ClientMetaInterceptor(String clientUUID) {
        this.clientUUID = clientUUID;
    }

    @Override
    public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
        return new ForwardingClientCall.SimpleForwardingClientCall<ReqT, RespT>(next.newCall(method, callOptions)) {
            @Override
            public void start(final Listener<RespT> responseListener, final Metadata headers) {
                headers.put(Metadata.Key.of("clientUUID", Metadata.ASCII_STRING_MARSHALLER), clientUUID);
                super.start(responseListener, headers);
            }
        };
    }
}

Error Details

This metadata key will automatically be generated by gRPC. To get it use the following java code. ErrorDetails is the java object created by the protobuf compiler from the message that contains the additional error information.

public static final Metadata.Key<ErrorDetails> ERROR_DETAILS_KEY = ProtoUtils.keyForProto( ErrorDetails.getDefaultInstance() );

The key generated above can be used to retrieve the data from the gRPC StatusRuntimeException as follows:

try {
        //execute a gRPC call that might fail...
        return blockingStub.someCallThatMightFail(...)
    } catch ( StatusRuntimeException e ) {
        ErrorDetails errorDetails =  Status.trailersFromThrowable( e ).get( ERROR_DETAILS_KEY );
    }

Previous

Overview

Next

REST Interface