CQL 模板 API (CQL Template API) | Spring Data for Apache Cassandra4.2.7中文文档|Spring官方文档|SpringBoot 教程|Spring中文网

对于最新的稳定版本，请使用 Spring Data Cassandra 4.3.1！

该类（及其反应式变体）是核心 CQL 包中的中心类。它处理资源的创建和发布。它执行核心 CQL 工作流的基本任务，例如语句创建和执行，并保留应用程序代码以提供 CQL 和提取结果。该类执行 CQL 查询和 update 语句，对实例执行迭代并提取返回的参数值。它还捕获 CQL 异常，并将其转换为包中定义的通用、信息量更大的异常层次结构。CqlTemplateReactiveCqlTemplateCqlTemplateResultSetorg.springframework.dao

当您在代码中使用时，您只需要实现具有明确定义的协定的回调接口。给定，回调接口使用提供的 CQL 和任何必要的参数参数创建一个预准备语句。该接口从 .CqlTemplateConnectionPreparedStatementCreatorRowCallbackHandlerResultSet

可以在 DAO 实现中使用，通过引用直接实例化，也可以在 Spring 容器中配置并作为 Bean 引用提供给 DAO。是 CassandraTemplate 的基础构建基块。CqlTemplateSessionFactoryCqlTemplate

此类颁发的所有 CQL 都记录在与模板实例的完全限定类名对应的类别下的级别（通常为，但如果使用类的自定义子类，则可能会有所不同）。DEBUGCqlTemplateCqlTemplate

您可以通过在 CQL API 实例上配置以下参数来控制提取大小、一致性级别和重试策略默认值：、和。如果未设置特定查询选项，则默认值适用。CqlTemplateAsyncCqlTemplateReactiveCqlTemplate

CqlTemplate有不同的执行模型风格。基本使用阻塞执行模型。您可以用于异步执行和与实例的同步，也可以用于响应式执行。CqlTemplateAsyncCqlTemplateListenableFutureReactiveCqlTemplate

类用法示例`CqlTemplate`

本节提供了该类的一些实际操作示例。这些示例并不是公开的所有功能的详尽列表。请参阅 Javadoc。CqlTemplateCqlTemplate

查询（SELECT）`CqlTemplate`

以下查询获取表中的行数：

Imperative
Reactive

int rowCount = cqlTemplate.queryForObject("SELECT COUNT(*) FROM t_actor", Integer.class);

Mono<Integer> rowCount = reactiveCqlTemplate.queryForObject("SELECT COUNT(*) FROM t_actor", Integer.class);

以下查询使用 bind 变量：

Imperative
Reactive

int countOfActorsNamedJoe = cqlTemplate.queryForObject(
		"SELECT COUNT(*) FROM t_actor WHERE first_name = ?", Integer.class, "Joe");

Mono<Integer> countOfActorsNamedJoe = reactiveCqlTemplate.queryForObject(
	"SELECT COUNT(*) FROM t_actor WHERE first_name = ?", Integer.class, "Joe");

以下示例查询：String

Imperative
Reactive

String lastName = cqlTemplate.queryForObject(
		"SELECT last_name FROM t_actor WHERE id = ?",
		String.class, 1212L);

Mono<String> lastName = reactiveCqlTemplate.queryForObject(
	"SELECT last_name FROM t_actor WHERE id = ?",
	String.class, 1212L);

以下示例查询并填充单个域对象：

Imperative
Reactive

Actor actor = cqlTemplate.queryForObject("SELECT first_name, last_name FROM t_actor WHERE id = ?",
		new RowMapper<Actor>() {
			public Actor mapRow(Row row, int rowNum) {
				Actor actor = new Actor();
				actor.setFirstName(row.getString("first_name"));
				actor.setLastName(row.getString("last_name"));
				return actor;
			}
		}, 1212L);

Mono<Actor> actor = reactiveCqlTemplate.queryForObject(
	"SELECT first_name, last_name FROM t_actor WHERE id = ?",
	new RowMapper<Actor>() {
		public Actor mapRow(Row row, int rowNum) {
			Actor actor = new Actor();
			actor.setFirstName(row.getString("first_name"));
			actor.setLastName(row.getString("last_name"));
			return actor;
		}},
	1212L);

以下示例查询并填充多个域对象：

Imperative
Reactive

List<Actor> actors = cqlTemplate.query(
		"SELECT first_name, last_name FROM t_actor",
		new RowMapper<Actor>() {
			public Actor mapRow(Row row, int rowNum) {
				Actor actor = new Actor();
				actor.setFirstName(row.getString("first_name"));
				actor.setLastName(row.getString("last_name"));
				return actor;
			}
		});

Flux<Actor> actors = reactiveCqlTemplate.query(
"SELECT first_name, last_name FROM t_actor",
	new RowMapper<Actor>() {
		public Actor mapRow(Row row, int rowNum) {
			Actor actor = new Actor();
			actor.setFirstName(row.getString("first_name"));
			actor.setLastName(row.getString("last_name"));
			return actor;
		}
});

如果最后两个代码片段确实存在于同一个应用程序中，那么删除两个匿名内部类中存在的重复项并将它们提取到一个类（通常是嵌套类）中是有意义的，然后 DAO 方法可以引用该类。RowMapperstatic

例如，最好按如下方式编写最后一个代码片段：

Imperative
Reactive

List<Actor> findAllActors() {
	return cqlTemplate.query("SELECT first_name, last_name FROM t_actor", ActorMapper.INSTANCE);
}

enum ActorMapper implements RowMapper<Actor> {

	INSTANCE;

	public Actor mapRow(Row row, int rowNum) {
		Actor actor = new Actor();
		actor.setFirstName(row.getString("first_name"));
		actor.setLastName(row.getString("last_name"));
		return actor;
	}
}

Flux<Actor> findAllActors() {
	return reactiveCqlTemplate.query("SELECT first_name, last_name FROM t_actor", ActorMapper.INSTANCE);
}

enum ActorMapper implements RowMapper<Actor> {

	INSTANCE;

	public Actor mapRow(Row row, int rowNum) {
		Actor actor = new Actor();
		actor.setFirstName(row.getString("first_name"));
		actor.setLastName(row.getString("last_name"));
		return actor;
	}
}

`INSERT`、和`UPDATEDELETECqlTemplate`

您可以使用该方法执行、和操作。参数值通常以变量参数的形式提供，或者作为对象数组提供。execute(…)INSERTUPDATEDELETE

以下示例演示如何使用：INSERTCqlTemplate

Imperative
Reactive

cqlTemplate.execute(
		"INSERT INTO t_actor (first_name, last_name) VALUES (?, ?)",
		"Leonor", "Watling");

Mono<Boolean> applied = reactiveCqlTemplate.execute(
	"INSERT INTO t_actor (first_name, last_name) VALUES (?, ?)",
	"Leonor", "Watling");

以下示例演示如何使用：UPDATECqlTemplate

Imperative
Reactive

cqlTemplate.execute(
		"UPDATE t_actor SET last_name = ? WHERE id = ?",
		"Banjo", 5276L);

Mono<Boolean> applied = reactiveCqlTemplate.execute(
	"UPDATE t_actor SET last_name = ? WHERE id = ?",
	"Banjo", 5276L);

以下示例演示如何使用：DELETECqlTemplate

Imperative
Reactive

cqlTemplate.execute(
		"DELETE FROM t_actor WHERE id = ?",
		5276L);

Mono<Boolean> applied = reactiveCqlTemplate.execute(
	"DELETE FROM actor WHERE id = ?",
	actorId);

其他操作`CqlTemplate`

您可以使用该方法执行任意 CQL。因此，该方法通常用于 DDL 语句。它被采用回调接口、绑定变量数组等的变体严重超载。execute(..)

以下示例演示如何使用全部传递给方法的不同 API 对象创建和删除表：execute()

		cqlTemplate.execute("CREATE TABLE test_table (id uuid primary key, event text)");

		DropTableSpecification dropper = DropTableSpecification.dropTable("test_table");
		String cql = DropTableCqlGenerator.toCql(dropper);

		cqlTemplate.execute(cql);

控制 Cassandra 连接

应用程序使用对象连接到 Apache Cassandra。 Cassandra 跟踪与各个节点的多个连接，并被设计为线程安全的长寿命对象。通常，您可以对整个应用程序使用单个应用程序。CqlSessionCqlSessionCqlSession

Spring 通过 . 是 Spring Data for Apache Cassandra 的一部分，是一个通用的连接工厂。它允许容器或框架从应用程序代码中隐藏连接处理和路由问题。CqlSessionSessionFactorySessionFactory

以下示例演示如何配置默认值：SessionFactory

Imperative
Reactive

CqlSession session = … // get a Cassandra Session

CqlTemplate template = new CqlTemplate();

template.setSessionFactory(new DefaultSessionFactory(session));

CqlSession session = … // get a Cassandra Session

ReactiveCqlTemplate template = new ReactiveCqlTemplate(new DefaultBridgedReactiveSession(session));

CqlTemplate和其他模板 API 实现为每个操作获取一个。由于会话的生存期很长，因此在调用所需操作后不会关闭会话。正确处理资源的责任在于使用会话的容器或框架。CqlSession

您可以在包中找到各种实现。SessionFactoryorg.springframework.data.cassandra.core.cql.session

异常翻译

Spring Framework 为各种数据库和映射技术提供异常转换。传统上，这是针对 JDBC 和 JPA 的。 Spring Data for Apache Cassandra 通过提供接口的实现将此功能扩展到 Apache Cassandra。org.springframework.dao.support.PersistenceExceptionTranslator

映射到 Spring 一致的数据访问异常层次结构背后的动机是让您编写可移植和描述性的异常处理代码，而无需针对特定的 Cassandra 异常进行编码和处理。 Spring 的所有数据访问异常都是从该类继承而来的，因此您可以确保可以在单个 try-catch 块中捕获所有与数据库相关的异常。DataAccessException

ReactiveCqlTemplate并尽早传播异常。在处理反应序列期间发生的异常将作为错误信号发出。ReactiveCassandraTemplate

类用法示例CqlTemplate

查询 （SELECT）CqlTemplate

INSERT、 和UPDATEDELETECqlTemplate