Object mappers in DSE drivers

The C#, Java, Node.js and Python drivers each provide an object mapper, which are tools for managing query results.

The C#, Java, Node.js and Python drivers each provide an object mapper. These mappers are tools for generating, executing, and consuming the results of queries.

The object mapper APIs intentionally do not implement all the CQL features. The mapper APIs differ for each language, as each language requires a different set of patterns. Examine the API documentation for each language to make sure it fits with your application.

The following concepts are common across the mapper APIs:

  • A model class is a class that represents a DSE table. These classes have member variables that map to columns in that table.
  • Instances of model classes are data objects.
Table 1. Obejct mapper API documentation for drivers
C/C++ (not supported) C# Java Node.js PHP (not supported) Python Ruby (not supported)

C# object mapper

In the C# object mapper, model classes are normal classes with setters and getters, also known as plain old CLR objects (POCOs). By default, the mapper automatically discovers the object member to DSE column name mapping. The mapping can also be explicitly configured by using the Define method.

Because model classes are POCOs, all queries must be mediated by the mapper object. Mappers wrap Session instances and provide methods, such as First and Fetch, that execute statements and define the types into which the mapper reads data. Similarly, mappers provide methods, such as Insert and Update, that take in a data object and use it to generate a write statement. All of these methods are generic and can take a parameterized query and arguments or a data object.

By default, writing null values deletes or unsets the corresponding value in the database. Writing null values creates tombstones that can impact query performance and the overall health of the database. Writing nulls can be controlled on a per-operation basis by setting insertNulls when using the Insert or InsertAsync methods.

The C# driver also includes a C# LINQ API available that will not be covered in detail in this guide.

Java object mapper

For the Java object mapper, model classes are created by annotating classes with @Table. By default, the mapper automatically discovers the object member to DSE column name mapping. The mapping can also be explicitly configured using the @Column annotation.

To execute queries with the mapper, create a data object that defines the query and pass it using CRUD operations on the mapper. For read queries, the data object arguments are used as filters on the DSE columns. If custom queries are needed, the mapper extends functionality via Accessors. It is also possible to map regular ResultSets to data objects. For write requests, the data object values are used as values in the insert query.

By default, writing null values deletes or unsets the corresponding value in the database. Writing null values creates tombstones that can impact query performance and the overall health of the database. Writing nulls can be controlled by default or on a per-operation basis by setting the saveNullFields option.

Node.js object mapper

For details on the Node.js object mapper, see this DataStax Academy blog post.

Python object mapper (cqlengine)

For the Python object mapper, model classes are created by subclassing cassandra.cqlengine.model.Model. By default, the mapper automatically discovers the mapping of object attributes created from cassandra.cqlengine.columns.Column to DSE column names. This mapping can also be explicitly defined using the db_field kwarg to Column subclass initializers.

It is safest to create the tables for model objects outside the scope of the mapper, though the Python driver does allow for making schema changes with the object mapper. Creating tables within the mapper can result in concurrent schema modifications, which are not recommended.

The Python mapper provides class methods for reading and writing data objects. In addition, queries can be executed by directly calling methods on the model class. The mapper read query methods return collections of data objects that have instance methods for CRUD operations.

Passing None corresponds to a DELETE operation on the value in the corresponding row. This creates tombstones that can impact query performance and the overall health of the database.

Mapper connections are maintained in a connection registry that can be used to access the sessions that connect to the database.