对于最新的稳定版本，请使用 Spring Data Cassandra 4.4.0！spring-doc.cn

持久化实体

位于包中的类（及其反应变体）是 Spring 的 Cassandra 支持中的中心类，并提供了丰富的功能集来与数据库交互。 该模板提供了用于创建、更新、删除和查询 Cassandra 的便捷操作，并在 Cassandra 表中提供域对象和行之间的映射。CassandraTemplateReactiveCassandraTemplateorg.springframework.data.cassandraspring-doc.cn

配置后，模板实例是线程安全的，并且可以在多个实例之间重复使用。

Cassandra 中的行和应用程序域类之间的映射是通过委托给接口的实现来完成的。 Spring 提供了一个默认的实现，但你也可以编写自己的自定义转换器。 请参阅 Cassandra 转换 部分 以了解更多详细信息。CassandraConverterMappingCassandraConverterspring-doc.cn

该类实现接口，其反应式变体 implements 。 上的方法尽可能以 Cassandra 中可用的方法命名，以使已经熟悉 Cassandra 的开发人员熟悉 API。CassandraTemplateCassandraOperationsReactiveCassandraTemplateReactiveCassandraOperations[Reactive]CassandraOperationsspring-doc.cn

例如，您可以找到 、 、 和 等方法 。 设计目标是尽可能轻松地在基本 Cassandra 驱动程序和 . 这两个 API 之间的主要区别是可以传递域对象，而不是 CQL 和查询对象。selectinsertdeleteupdate[Reactive]CassandraOperationsCassandraOperationsspring-doc.cn

引用实例上的操作的首选方式是通过界面。[Reactive]CassandraTemplate[Reactive]CassandraOperations

使用的默认转换器实现是 。 虽然可以使用其他元数据来指定对象到行的映射，但它也可以通过使用一些约定来转换不包含其他元数据的对象，以便对字段和表名的映射进行映射。 这些约定以及映射注释的使用将在 “映射” 一章中解释。[Reactive]CassandraTemplateMappingCassandraConverterMappingCassandraConverterspring-doc.cn

的另一个核心功能是将 Cassandra Java 驱动程序中抛出的异常转换为 Spring 的可移植数据访问异常层次结构。 请参阅 异常转换 以了解更多信息。[Reactive]CassandraTemplatespring-doc.cn

模板 API 具有不同的执行模型风格。 基本使用阻塞 （命令式同步） 执行模型。 您可以用于异步执行和与实例同步，也可以用于反应执行。CassandraTemplateAsyncCassandraTemplateListenableFutureReactiveCassandraTemplate

实例化CassandraTemplate

CassandraTemplate应该始终配置为 Spring bean，尽管我们前面展示了一个可以直接实例化它的示例。 但是，由于我们假设了创建 Spring 模块的上下文，因此我们假设存在 Spring 容器。spring-doc.cn

有两种方法可以获取 ，具体取决于您加载 Spring 的方式：CassandraTemplateApplicationContextspring-doc.cn

自动装配

您可以将 自动装配到项目中，如下例所示：[Reactive]CassandraOperationsspring-doc.cn

@Autowired
private CassandraOperations cassandraOperations;
@Autowired
private ReactiveCassandraOperations reactiveCassandraOperations;

与所有 Spring 自动装配一样，这假定 . 如果你有多个 bean（如果你在同一个项目中使用多个键空间，就是这种情况），那么你可以使用 Comments 来指定要自动装配的 bean。[Reactive]CassandraOperationsApplicationContext[Reactive]CassandraTemplate@Qualifierspring-doc.cn

@Autowired
@Qualifier("keyspaceOneTemplateBeanId")
private CassandraOperations cassandraOperations;
@Autowired
@Qualifier("keyspaceOneTemplateBeanId")
private ReactiveCassandraOperations reactiveCassandraOperations;

Bean 查找ApplicationContext

您还可以从 中查找 bean，如以下示例所示：[Reactive]CassandraTemplateApplicationContextspring-doc.cn

CassandraOperations cassandraOperations = applicationContext.getBean("cassandraTemplate", CassandraOperations.class);
ReactiveCassandraOperations cassandraOperations = applicationContext.getBean("ReactiveCassandraOperations", ReactiveCassandraOperations.class);

查询行

您可以使用 and 类来表示查询，这些类具有反映本机 Cassandra 谓词运算符名称的方法名称，例如 、 、 等。QueryCriterialtlteisspring-doc.cn

和 类遵循 Fluent API 样式，因此您可以轻松地将多个方法条件和查询链接在一起，同时拥有易于理解的代码。 在 Java 中创建实例时使用静态导入来提高可读性。QueryCriteriaQueryCriteriaspring-doc.cn

查询表中的行

在前面的部分中，我们了解了如何使用 on 方法检索单个对象。 这样做将返回单个域对象。 我们还可以查询要作为域对象列表返回的行集合。 假设我们在表中将许多具有 name 和 age 值的对象存储为行，并且每个人都有账户余额，我们现在可以使用以下代码运行查询：selectOneById[Reactive]CassandraTemplatePersonspring-doc.cn

使用 查询行[Reactive]CassandraTemplate
import static org.springframework.data.cassandra.core.query.Criteria.where;
import static org.springframework.data.cassandra.core.query.Query.query;

…

List<Person> result = cassandraTemplate.select(query(where("age").is(50))
  .and(where("balance").gt(1000.00d)).withAllowFiltering(), Person.class);
import static org.springframework.data.cassandra.core.query.Criteria.where;
import static org.springframework.data.cassandra.core.query.Query.query;

…

Flux<Person> result = reactiveCassandraTemplate.select(query(where("age").is(50))
  .and(where("balance").gt(1000.00d)).withAllowFiltering(), Person.class);

、 和 方法将对象作为参数。 此对象定义用于执行查询的条件和选项。 条件是使用一个对象指定的，该对象具有一个名为 Static Factory Method 的对象，该方法用于实例化一个新对象。 我们建议对 和 使用静态导入，以使查询更具可读性。selectselectOnestreamQueryCriteriawhereCriteriaorg.springframework.data.cassandra.core.query.Criteria.whereQuery.queryspring-doc.cn

此查询应返回满足指定条件的对象列表。 该类具有以下方法，这些方法对应于 Apache Cassandra 中提供的运算符：PersonCriteriaspring-doc.cn

Criteria 类的方法

  • CriteriaDefinition gt ：使用运算符创建标准。(Object value)>spring-doc.cn

  • CriteriaDefinition gte ：使用运算符创建标准。(Object value)>=spring-doc.cn

  • CriteriaDefinition in ：使用 varargs 参数的运算符创建标准。(Object…​ values)INspring-doc.cn

  • CriteriaDefinition in ：使用运算符和集合创建标准。(Collection<?> collection)INspring-doc.cn

  • CriteriaDefinition is ：使用字段匹配 （） 创建标准。(Object value)column = valuespring-doc.cn

  • CriteriaDefinition lt ：使用运算符创建条件。(Object value)<spring-doc.cn

  • CriteriaDefinition lte ：使用运算符创建标准。(Object value)⇐spring-doc.cn

  • CriteriaDefinition like ：使用运算符创建标准。(Object value)LIKEspring-doc.cn

  • CriteriaDefinition contains ：使用运算符创建标准。(Object value)CONTAINSspring-doc.cn

  • CriteriaDefinition containsKey ：使用运算符创建标准。(Object key)CONTAINS KEYspring-doc.cn

Criteria一旦创建，就不可变。spring-doc.cn

Query 类的方法

该类具有一些其他方法，您可以使用这些方法为查询提供选项：Queryspring-doc.cn

  • Query by ：用于创建对象。(CriteriaDefinition…​ criteria)Queryspring-doc.cn

  • Query 和 ： 用于向查询添加其他条件。(CriteriaDefinition criteria)spring-doc.cn

  • Query columns ：用于定义要包含在查询结果中的列。(Columns columns)spring-doc.cn

  • Query limit ：用于将返回结果的大小限制为提供的限制（用于限制）。(Limit limit)SELECTspring-doc.cn

  • Query limit ：用于将返回结果的大小限制为提供的限制（用于限制）。(long limit)SELECTspring-doc.cn

  • Query pageRequest ：用于将 、 和 与查询（用于分页）关联。(Pageable pageRequest)SortPagingStatefetchSizespring-doc.cn

  • Query pagingState ：用于将 a 与查询关联（用于分页）。(ByteBuffer pagingState)ByteBufferspring-doc.cn

  • Query queryOptions ：用于与查询关联。(QueryOptions queryOptions)QueryOptionsspring-doc.cn

  • Query sort ：用于为结果提供排序定义。(Sort sort)spring-doc.cn

  • Query withAllowFiltering ：用于呈现查询。()ALLOW FILTERINGspring-doc.cn

Query一旦创建，就不可变。 调用方法会创建新的不可变（中间）对象。Queryspring-doc.cn

查询行的方法

该类具有以下返回 rows 的方法：Queryspring-doc.cn

  • List<T> select ：查询表中类型的对象列表。(Query query, Class<T> entityClass)Tspring-doc.cn

  • T selectOne ：从表中查询单个对象类型。(Query query, Class<T> entityClass)Tspring-doc.cn

  • Slice<T> slice ：通过从表中查询 of 对象类型来开始或继续分页。(Query query, Class<T> entityClass)SliceTspring-doc.cn

  • Stream<T> stream ：从表中查询 type 对象的流。(Query query, Class<T> entityClass)Tspring-doc.cn

  • List<T> select ： 通过提供 CQL 语句，对表中对象类型的列表进行临时查询。(String cql, Class<T> entityClass)Tspring-doc.cn

  • T selectOne ：通过提供 CQL 语句，对表中的单个对象类型进行临时查询。(String cql, Class<T> entityClass)Tspring-doc.cn

  • Stream<T> stream ：通过提供 CQL 语句，对表中对象类型的流进行临时查询。(String cql, Class<T> entityClass)Tspring-doc.cn

查询方法必须指定返回的目标类型。Tspring-doc.cn

Fluent 模板 API

当涉及到 Apache Cassandra 的更多底层交互时，该接口是核心组件之一。 它提供了多种方法。 您可以找到每个方法的多个重载。 它们中的大多数涵盖了 API 的可选 （可为 null） 部分。[Reactive]CassandraOperationsspring-doc.cn

FluentCassandraOperations及其反应式变体为提供更可读、更流畅的 API 的常用方法提供了一个更窄的接口。 入口点 （、 、 和 ）遵循基于要执行的操作的自然命名方案。 从入口点开始，API 旨在仅提供依赖于上下文的方法，这些方法将指导开发人员使用调用实际 . 以下示例显示了 Fluent API：ReactiveFluentCassandraOperations[Reactive]CassandraOperationsquery(…)insert(…)update(…)delete(…)[Reactive]CassandraOperationsspring-doc.cn

List<SWCharacter> all = ops.query(SWCharacter.class)
  .inTable("star_wars")                        (1)
  .all();
1 如果使用类名定义表名，或者使用类名作为表名没有问题，请跳过此步骤SWCharacter@Table 
Flux<SWCharacter> all = ops.query(SWCharacter.class)
  .inTable("star_wars")                        (1)
  .all();
1 如果使用类名定义表名，或者使用类名作为表名没有问题，请跳过此步骤SWCharacter@Table

如果 Cassandra 中的表包含不同类型的实体，例如 Table 中的 a ，则可以使用不同类型的实体来映射查询结果。 可用于将结果映射到其他目标类型，同时仍适用于查询和表名称。 以下示例使用 and 方法：JediSWCharactersas(Class<?> targetType)query(Class<?> entityType)queryasspring-doc.cn

List<Jedi> all = ops.query(SWCharacter.class)    (1)
  .as(Jedi.class)                                (2)
  .matching(query(where("jedi").is(true)))
  .all();
1 查询字段将针对类型进行映射。SWCharacter
2 生成的行将映射到 。Jedi 
Flux<Jedi> all = ops.query(SWCharacter.class)    (1)
  .as(Jedi.class)                                (2)
  .matching(query(where("jedi").is(true)))
  .all();
1 查询字段将针对类型进行映射。SWCharacter
2 生成的行将映射到 。Jedi
您可以通过 .interfaceas(Class<?>)

终止方法 （、 、 和 ）处理检索单个实体和检索多个实体作为 or 和类似操作之间的切换。first()one()all()stream()ListStreamspring-doc.cn

新的 Fluent 模板 API 方法（即 、 、 和 ）使用有效的线程安全支持对象来编写 CQL 语句。 但是，这是以额外的年轻一代 JVM 堆开销为代价的，因为该设计基于各种 CQL 语句组件的最终字段和更改构造。 在可能插入或删除大量对象时（例如，在循环内部），您应该小心。query(..)insert(..)update(..)delete(..)

保存、更新和删除行

[Reactive]CassandraTemplate为您提供了一种简单的方法来保存、更新和删除域对象，并将这些对象映射到在 Cassandra 中托管的表。spring-doc.cn

类型映射

Spring Data for Apache Cassandra 依赖于 DataStax Java 驱动程序来确保类型支持。 添加或更改类型时，Spring Data for Apache Cassandra 模块将继续运行，而无需更改。 有关当前类型映射矩阵，请参阅 CQL 数据类型和“数据映射和类型转换”。CodecRegistryspring-doc.cn

插入和更新行的方法

[Reactive]CassandraTemplate有几种保存和插入对象的便捷方法。 要对转换过程进行更精细的控制，可以使用 （例如，） 注册 Spring 实例。ConverterMappingCassandraConverterConverter<Row, Person>spring-doc.cn

插入操作和更新操作之间的区别在于操作不插入值。INSERTnull

使用该操作的简单情况是保存一个 POJO。 在这种情况下，table 名由简单类名（而不是完全限定的类名）确定。 可以使用映射元数据覆盖用于存储对象的表。INSERTspring-doc.cn

插入或更新时，必须设置该属性。 Apache Cassandra 无法生成 ID。idspring-doc.cn

以下示例使用 save 操作并检索其内容：spring-doc.cn

使用[Reactive]CassandraTemplate
import static org.springframework.data.cassandra.core.query.Criteria.where;
import static org.springframework.data.cassandra.core.query.Query.query;
…

Person bob = new Person("Bob", 33);
cassandraTemplate.insert(bob);

Person queriedBob = cassandraTemplate.selectOneById(query(where("age").is(33)), Person.class);
import static org.springframework.data.cassandra.core.query.Criteria.where;
import static org.springframework.data.cassandra.core.query.Query.query;
…

Person bob = new Person("Bob", 33);
cassandraTemplate.insert(bob);

Mono<Person> queriedBob = reactiveCassandraTemplate.selectOneById(query(where("age").is(33)), Person.class);

您可以通过以下操作进行 insert 和 save：spring-doc.cn

  • void insert ：将对象插入 Apache Cassandra 表中。(Object objectToSave)spring-doc.cn

  • WriteResult insert ：将对象插入 Apache Cassandra 表中并应用 。(Object objectToSave, InsertOptions options)InsertOptionsspring-doc.cn

您可以使用以下更新操作：spring-doc.cn

  • void update ：更新 Apache Cassandra 表中的对象。(Object objectToSave)spring-doc.cn

  • WriteResult update ：更新 Apache Cassandra 表中的对象并应用 .(Object objectToSave, UpdateOptions options)UpdateOptionsspring-doc.cn

您还可以使用老式方式编写自己的 CQL 语句，如下例所示：spring-doc.cn

String cql = "INSERT INTO person (age, name) VALUES (39, 'Bob')";

cassandraTemplate().getCqlOperations().execute(cql);
String cql = "INSERT INTO person (age, name) VALUES (39, 'Bob')";

Mono<Boolean> applied = reactiveCassandraTemplate.getReactiveCqlOperations().execute(cql);

您还可以在使用 和 时配置其他选项，如 TTL、一致性级别和轻量级事务。InsertOptionsUpdateOptionsspring-doc.cn

我的行插入到哪个表中？

您可以通过两种方式管理用于对表进行操作的表名。 默认表名是更改为以小写字母开头的简单类名。 因此，该类的实例将存储在表中。 第二种方法是在 annotation 中指定 table name。com.example.Personperson@Tablespring-doc.cn

在批处理中插入、更新和删除单个对象

Cassandra 协议支持使用批处理在一个操作中插入行集合。spring-doc.cn

接口中的以下方法支持此功能：[Reactive]CassandraTemplatespring-doc.cn

  • batchOps：创建一个新的 register 以填充批处理。[Reactive]CassandraBatchOperationsspring-doc.cn

[Reactive]CassandraBatchOperationsspring-doc.cn

  • insert：接受要插入的单个对象、数组 （var-args） 或对象。Iterablespring-doc.cn

  • update：接受要更新的单个对象、数组 （var-args） 或对象。Iterablespring-doc.cn

  • delete：获取要删除的单个对象、数组 （var-args） 或对象。Iterablespring-doc.cn

  • withTimestamp：将 TTL 应用于批处理。spring-doc.cn

  • execute：执行批处理。spring-doc.cn

更新表中的行

对于更新，您可以选择更新多个行。spring-doc.cn

以下示例显示了通过向分配余额添加一次性 50.00 USD 奖金来更新单个账户对象：+spring-doc.cn

使用 更新行[Reactive]CasandraTemplate
import static org.springframework.data.cassandra.core.query.Criteria.where;
import org.springframework.data.cassandra.core.query.Query;
import org.springframework.data.cassandra.core.query.Update;

…

boolean applied = cassandraTemplate.update(Query.query(where("id").is("foo")),
  Update.create().increment("balance", 50.00), Account.class);
import static org.springframework.data.cassandra.core.query.Criteria.where;
import org.springframework.data.cassandra.core.query.Query;
import org.springframework.data.cassandra.core.query.Update;

…

Mono<Boolean> wasApplied = reactiveCassandraTemplate.update(Query.query(where("id").is("foo")),
  Update.create().increment("balance", 50.00), Account.class);

除了前面讨论的内容之外，我们还使用对象提供更新定义。 该类具有与 Apache Cassandra 可用的更新分配匹配的方法。QueryUpdateUpdatespring-doc.cn

大多数方法返回对象以提供 Fluent API 用于代码样式设置。Updatespring-doc.cn

执行行更新的方法

update 方法可以更新行，如下所示：spring-doc.cn

  • boolean update ：更新 Apache Cassandra 表中的选定对象。(Query query, Update update, Class<?> entityClass)spring-doc.cn

Update 类的方法

该类可以与一点“语法糖”一起使用，因为它的方法应该链接在一起。 此外，您还可以使用 static 方法和 static 导入来启动新实例的创建。UpdateUpdatepublic static Update update(String key, Object value)spring-doc.cn

该类具有以下方法：Updatespring-doc.cn

  • AddToBuilder addTo 入口点：(String columnName)AddToBuilderspring-doc.cn

    • Update ：使用 update 分配将集合值添加到现有集合的前面。prepend(Object value)+spring-doc.cn

    • Update ：使用 update 分配将所有集合值添加到现有集合的前面。prependAll(Object…​ values)+spring-doc.cn

    • Update ：使用 update 分配将集合值附加到现有集合。append(Object value)+spring-doc.cn

    • Update ：使用 update 分配将所有集合值附加到现有集合。append(Object…​ values)+spring-doc.cn

    • Update ：使用 update 分配添加映射条目。entry(Object key, Object value)+spring-doc.cn

    • Update ：使用更新分配将所有映射条目添加到映射中。addAll(Map<? extends Object, ? extends Object> map)+spring-doc.cn

  • Update remove ：使用 update 分配从集合中删除值。(String columnName, Object value)-spring-doc.cn

  • Update clear ：清除集合。(String columnName)spring-doc.cn

  • Update increment ：使用 update 分配进行更新。(String columnName, Number delta)+spring-doc.cn

  • Update decrement ：使用 update 分配进行更新。(String columnName, Number delta)-spring-doc.cn

  • Update set ：使用 update 分配进行更新。(String columnName, Object value)=spring-doc.cn

  • SetBuilder set entry-point 设置入口点：(String columnName)SetBuilderspring-doc.cn

    • Update ：使用更新分配将给定索引处的集合设置为值。atIndex(int index).to(Object value)=spring-doc.cn

    • Update ：将给定键处的映射条目设置为更新分配的值。atKey(String object).to(Object value)=spring-doc.cn

下面的清单显示了一些更新示例：spring-doc.cn

// UPDATE … SET key = 'Spring Data';
Update.update("key", "Spring Data")

// UPDATE … SET key[5] = 'Spring Data';
Update.empty().set("key").atIndex(5).to("Spring Data");

// UPDATE … SET key = key + ['Spring', 'DATA'];
Update.empty().addTo("key").appendAll("Spring", "Data");

请注意，一旦创建，它是不可变的。 调用方法会创建新的不可变（中间）对象。UpdateUpdatespring-doc.cn

删除行的方法

您可以使用以下重载方法从数据库中删除对象：spring-doc.cn

  • boolean delete ：删除 选择的对象。(Query query, Class<?> entityClass)Queryspring-doc.cn

  • T delete ：删除给定的对象。(T entity)spring-doc.cn

  • T delete ：应用 删除给定的对象。(T entity, QueryOptions queryOptions)QueryOptionsspring-doc.cn

  • boolean deleteById ：使用给定的 ID 删除对象。(Object id, Class<?> entityClass)spring-doc.cn

乐观锁定

该注释提供的语法类似于 Cassandra 上下文中的 JPA 语法，并确保更新仅应用于具有匹配版本的行。 Optimistic Locking 利用 Cassandra 的轻量级事务有条件地插入、更新和删除行。 因此，语句是使用 condition. 对于更新和删除，将 version 属性的实际值添加到条件中，这样，如果另一个操作同时更改了该行，则修改不会产生任何影响。 在这种情况下，将引发 an。 以下示例显示了这些功能：@VersionINSERTIF NOT EXISTSUPDATEOptimisticLockingFailureExceptionspring-doc.cn

@Table
class Person {

  @Id String id;
  String firstname;
  String lastname;
  @Version Long version;
}

Person daenerys = template.insert(new Person("Daenerys"));                            (1)

Person tmp = template.findOne(query(where("id").is(daenerys.getId())), Person.class); (2)

daenerys.setLastname("Targaryen");
template.save(daenerys);                                                              (3)

template.save(tmp); // throws OptimisticLockingFailureException                       (4)
1 最初插入文档。 设置为 。version0
2 加载刚刚插入的文档。 仍然是 。version0
3 使用 更新文档。 将 and bump 设置为 。version = 0lastnameversion1
4 尝试更新以前加载的仍具有 . 操作失败并显示 ，因为电流为 。version = 0OptimisticLockingFailureExceptionversion1
Optimistic Locking 仅支持单实体操作，不支持批处理操作。