Stargate gRPC API client creation

Stargate has a gRPC server implemented as part of the gRPC API. You can create a gRPC client to use Stargate in any language that gRPC supports. This section provides information to developers that wish to create a client in a language not yet supported.

Client creation

This quote from gRPC.io provides context to why you might wish to create a gRPC client:

In gRPC, a client application can directly call a method on a server application on a different machine as if it were a local object, making it easier for you to create distributed applications and services. As in many RPC systems, gRPC is based around the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. On the server side, the server implements this interface and runs a gRPC server to handle client calls. On the client side, the client has a stub (referred to as just a client in some languages) that provides the same methods as the server.

The Stargate gRPC API implements two query services, standard and batch.

The standard service executes a single Cassandra Query Language (CQL) query. The batch service executes a batch of CQL queries.

Proto files

The stargate.proto file provides these services that interact with a Stargate coordinator to execute CQL queries. The query.proto file identifies the relevant messages required to interact with CQL. These include:

Type values, including some special elements that need additional message definitions
Values
Query strings
Query parameters
Metadata about columns
Tracing information
Schema change information, including the object (keyspace, table, etc.) changed
Query response
ResultSet of values returned from a query
Batch queries
Batch parameters
Errors

When a language-specific proto file is generated from these two files, the services provided allow a gRPC client to interact with Apache Cassandra through Stargate.

Generate gRPC classes for a language

This section is possibly the most “black-boxed” part of the whole process. Each language has special tools to automatically generate classes from the proto files. When the appropriate tools are run, new files will be generated.

For example, in Python, the following commands are run to generate the required protobuf files:

$ pip install grpcio
$ pip install grpcio-tools

$ python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. stargate.proto
$ python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. query.proto

The generated files generated are:

query_pb2.py — contains message classes
query_grpc_pb2.py — contains server and client classes
stargate_pb2.py - contains message classes
stargate_pb2_grpc.py — contains server and client classes

Client code

Examples of some gRPC clients written for Stargate exist to provide samples of how a new client can be created.