Apache Ignite SQL API 深度解析与实战指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01034/article/details/148524007

Apache Ignite SQL API 深度解析与实战指南

ignite Apache Ignite 项目地址: https://gitcode.com/gh_mirrors/ignite16/ignite

一、Ignite SQL API 概述

Apache Ignite 提供了一套强大的 SQL API，允许开发者直接通过编程接口执行 SQL 查询和数据操作，而不仅限于使用 JDBC 驱动。这套 API 的核心是 SqlFieldsQuery 类，它为执行 SQL 语句和遍历结果集提供了统一的接口。

与传统的 JDBC 方式相比，Ignite SQL API 具有以下优势：

更紧密的集成：直接与 Ignite 缓存交互，无需额外的驱动配置
更灵活的控制：可以精细控制查询行为（如本地执行、超时设置等）
更好的性能：减少了协议转换的开销

二、配置可查询字段

在使用 SQL 查询缓存前，必须明确指定哪些字段可以被 SQL 引擎识别和查询。Ignite 提供了两种配置方式：

1. 使用 @QuerySqlField 注解

通过在值对象的字段上添加 @QuerySqlField 注解，可以快速定义可查询字段：

public class Person implements Serializable {
    @QuerySqlField
    private long id;
    
    @QuerySqlField(index = true)  // 带索引的字段
    private String name;
    
    @QuerySqlField
    private int age;
}

配置缓存时需要调用 setIndexedTypes() 方法注册这些类型：

CacheConfiguration<Long, Person> cfg = new CacheConfiguration<Long, Person>()
    .setName("Person")
    .setIndexedTypes(Long.class, Person.class);

2. 使用 QueryEntity 配置

对于 XML 配置或需要更灵活的场景，可以使用 QueryEntity：

<bean class="org.apache.ignite.configuration.CacheConfiguration">
    <property name="name" value="Person"/>
    <property name="queryEntities">
        <list>
            <bean class="org.apache.ignite.cache.QueryEntity">
                <property name="keyType" value="java.lang.Long"/>
                <property name="valueType" value="org.example.Person"/>
                <property name="fields">
                    <map>
                        <entry key="id" value="java.lang.Long"/>
                        <entry key="name" value="java.lang.String"/>
                        <entry key="age" value="java.lang.Integer"/>
                    </map>
                </property>
            </bean>
        </list>
    </property>
</bean>

三、执行 SQL 查询

基础查询示例

IgniteCache<Long, Person> cache = ignite.cache("Person");

// 创建查询对象
SqlFieldsQuery sql = new SqlFieldsQuery(
    "SELECT p.name, p.age FROM Person p WHERE p.age > ?");

// 执行查询
try (QueryCursor<List<?>> cursor = cache.query(sql.setArgs(30))) {
    for (List<?> row : cursor)
        System.out.println("Name: " + row.get(0) + ", Age: " + row.get(1));
}

查询模式详解

分布式查询：默认模式，查询会在整个集群中执行
本地查询：仅在当前节点数据上执行（可能结果不完整）

// 强制本地执行
sql.setLocal(true);

子查询限制：WHERE 子句中的子查询只能在本地执行

-- 这个子查询不会分布式执行
DELETE FROM Person WHERE id IN 
    (SELECT personId FROM Salary WHERE amount > 2000);

四、数据操作（DML）

Ignite SQL API 支持完整的 DML 操作：

1. 插入数据

cache.query(new SqlFieldsQuery(
    "INSERT INTO Person(id, name, age) VALUES (?, ?, ?)")
    .setArgs(1L, "John Doe", 35));

2. 更新数据

cache.query(new SqlFieldsQuery(
    "UPDATE Person SET age = ? WHERE name = ?")
    .setArgs(36, "John Doe"));

3. 删除数据

cache.query(new SqlFieldsQuery(
    "DELETE FROM Person WHERE age < ?")
    .setArgs(30));

4. 合并数据（UPSERT）

cache.query(new SqlFieldsQuery(
    "MERGE INTO Person(id, name, age) VALUES (?, ?, ?)")
    .setArgs(1L, "John Doe", 37));

五、模式（Schema）管理

Ignite 支持多模式操作：

// 显式设置模式
SqlFieldsQuery sql = new SqlFieldsQuery("SELECT * FROM City")
    .setSchema("PERSON");

// 或者在SQL中直接指定
SqlFieldsQuery sql = new SqlFieldsQuery("SELECT * FROM Person.City");

六、表操作（DDL）

通过 SQL API 可以执行 DDL 语句：

// 创建表
cache.query(new SqlFieldsQuery(
    "CREATE TABLE City (id LONG PRIMARY KEY, name VARCHAR, region VARCHAR)")
    .setSchema("PUBLIC")).getAll();

// 创建索引
cache.query(new SqlFieldsQuery(
    "CREATE INDEX idx_city_name ON City (name)")).getAll();

七、高级特性

1. 表连接查询

SqlFieldsQuery qry = new SqlFieldsQuery(
    "SELECT o.name FROM Organization o " +
    "JOIN Person p ON o.id = p.orgId " +
    "JOIN City c ON c.name = o.cityName " +
    "WHERE p.age > 25 AND c.region <> 'Texas'")
    .setSchema("PUBLIC");

2. 查询取消机制

方式一：设置超时

// 设置5秒超时
sql.setTimeout(5, TimeUnit.SECONDS);

方式二：手动取消

try (QueryCursor<List<?>> cursor = cache.query(sql)) {
    // 处理部分结果后取消
    for (List<?> row : cursor) {
        if (shouldCancel())
            break;  // 自动关闭cursor
    }
}