Submit queries with Cassandra drivers
The ability to submit read/write queries (statements) to your database is the core purpose of Cassandra drivers.
This page introduces standard query execution. Explore the other topics in this guide and your driver’s documentation for more information, such as query performance optimization, error handling, and advanced usage.
C/C++ driver statement execution
For the quickstart, see Executing queries with the C/C++ driver.
For more advanced usage, explore other topics in your driver’s documentation, such as Parameterized queries (positional) and Batches.
For information about data type representation, see CassDataType.
C# driver statement execution
For the quickstart, see Basic usage of the C# driver.
For more information and advanced usage, see Statements in the C# driver.
For information about data type representation, see CQL data types to C# types.
GoCQL driver statement execution
For the quickstart, see Executing queries with the GoCQL driver.
For more information and advanced usage, see GoCQL examples and the GoCQL reference.
GoCQL supports automatic type conversion between Cassandra and Go, as well as support for custom types.
Java driver statement execution
See the documentation for your version of the Java driver:
Node.js driver statement execution
For the quickstart, see Getting started with the Node.js driver.
For more information, explore other topics in the Node.js driver documentation, such as Batch statements.
For information about data type representation, see CQL data types to JavaScript types.
PHP driver statement execution
For the quickstart, see Executing queries with the PHP driver.
For more information, explore other topics in the PHP driver documentation, such as Simple statements and Batch statements.
For information about data type representation, see Datatypes.
Python driver statement execution
For the quickstart, see Executing queries with the Python driver.
For more information, explore other topics in the Python driver documentation, such as Batch queries.
For information about data type representation, explore other topics in the Python driver documentation, such as cassandra.encoder and Working with dates and times.
Ruby driver statement execution
For the quickstart, see Executing queries with the Ruby driver.
For more information, explore other topics in the Ruby driver documentation, such as Batch statements.
For information about data type representation, see Datatypes.
|
Don’t create |
Synchronous and asynchronous query execution
Cassandra drivers can execute queries against a database synchronously or asynchronously. The appropriate choice for your application depends on your use cases and requirements.
DataStax drivers execute queries synchronously by default, except for the Node.js driver, which supports only asynchronous query execution.
This means that the application sends a query to the database, and then the thread that sent the query waits for the query to complete before proceeding. In multi-threaded applications, other threads can continue to run while the query is processed. In single-threaded applications, this can block the entire application while waiting for the query result.
With synchronous query execution, it is easy to tell when a query completes, and this can make the application’s execution logic easier to follow.
However, each thread can only execute one query at a time. While server nodes usually take less than a millisecond to fulfill a request, throughput can degrade when executing extremely large numbers of queries or while waiting for long-running queries to finish. If your application needs to process thousands or millions of queries, asynchronous query execution can be more performant.
Set request timeouts
You can set a request timeout for each CQL statement.
To determine the ideal timeout value, consider that each query execution can require multiple actions:
-
Default request execution with no retries or additional handling.
-
Sending requests to multiple nodes if the initial attempt fails (retries).
-
Scheduling and executing speculative retries.
-
Establishing new node connections if other connections are already executing the maximum number of concurrent requests.
-
Repreparing CQL statements if a prepared statement ID wasn’t found on the server.
-
Executing custom
RequestTrackerimplementations, if applicable to the driver.
Additionally, DataStax recommends higher timeouts for DDL statements because they can take longer to execute. For example, in Apache Cassandra® 5.0 and later, DDL statements are executed sequentially.
C/C++ driver statement timeouts
See CassStatement and Execution profiles.
C# driver statement timeouts
You can set timeouts in the Session.Execute() and Session.ExecuteAsync() methods.
For more information, see C# driver statements and Execution profiles.
GoCQL driver statement timeouts
See ClusterConfig.Timeout and Execution profiles.
Java driver statement timeouts
The timeout declared on the CQL statement is the global timeout for execution of the query.
For more information, see the documentation for your version of the Java driver:
You can also set timeouts in execution profiles.
Node.js driver statement timeouts
See ExecutionOptions and Execution profiles.
Python driver statement timeouts
You can set query timeouts in session.execute().
rows = session.execute("CREATE TABLE cycling.race_winners (
race_name text,
race_position int,
cyclist_name FROZEN<fullname>,
PRIMARY KEY (race_name, race_position));
", timeout=10)You can also set timeouts in execution profiles.
Ruby driver statement timeouts
You can set query timeouts in session.execute and Execution profiles.
Increase the default request timeout limit
By default, most drivers have a basic request timeout of 2 seconds. DataStax recommends increasing this limit to 10 seconds for most applications.
Be aware that the basic request timeout isn’t a global timeout for all queries.
For example, when the Java driver sends a query to retrieve metadata, such as SELECT * FROM system_schema.keyspaces, it uses the control connection timeout, which is separate from the basic request timeout.
For the Java driver, other timeouts are set in advanced.connection, whereas request timeouts are set in basic.request.
For more information about setting timeouts, see your driver’s documentation.
Set consistency levels
Consistency levels determine how many replicas in a cluster must acknowledge a read or write operation before it is considered successful.
C/C++ driver consistency
C# driver consistency
The C# driver provides a common set of query attributes that you can set through setters, including ConsistencyLevel.
GoCQL driver consistency
The GoCQL driver provides several mechanisms for setting consistency level, such as Consistency and Query.SerialConsistency.
Java driver consistency
See the documentation for your version of the Java driver:
