Apache Zeppelin 的 Cassandra CQL 解释器

启用Cassandra解释器

在笔记本中，要启用Cassandra解释器，请点击齿轮图标并选择Cassandra

使用Cassandra解释器

在段落中，使用%cassandra来选择Cassandra解释器，然后输入所有命令。

要访问交互式帮助，请输入 HELP;

解释器命令

Cassandra 解释器接受以下命令

CQL 语句

此解释器与Cassandra支持的任何CQL语句兼容。例如：

INSERT INTO users(login,name) VALUES('jdoe','John DOE');
SELECT * FROM users WHERE login='jdoe';

每个语句应该用分号（;）分隔，除了以下特殊命令：

1. @prepare
2. @bind
3. @remove_prepare
4. @consistency
5. @serialConsistency
6. @timestamp
7. @fetchSize
8. @requestTimeOut

多行语句以及同一行上的多个语句也支持，只要它们用分号分隔。例如：

USE spark_demo;

SELECT * FROM albums_by_country LIMIT 1; SELECT * FROM countries LIMIT 1;

SELECT *
FROM artists
WHERE login='jlennon';

支持批处理语句，并且可以跨越多行，以及DDL（CREATE/ALTER/DROP）语句：

BEGIN BATCH
    INSERT INTO users(login,name) VALUES('jdoe','John DOE');
    INSERT INTO users_preferences(login,account_type) VALUES('jdoe','BASIC');
APPLY BATCH;

CREATE TABLE IF NOT EXISTS test(
    key int PRIMARY KEY,
    value text
);

CQL语句是不区分大小写的（除了列名和值）。这意味着以下语句是等效且有效的：

INSERT INTO users(login,name) VALUES('jdoe','John DOE');
Insert into users(login,name) vAlues('hsue','Helen SUE');

所有CQL语句和版本的完整列表可以在下面找到：

语句中的注释

可以在语句之间添加注释。单行注释以井号（#）、双斜杠（//）、双破折号（--）开头。多行注释则包含在/**和**/之间。例如：

# Single line comment style 1
INSERT INTO users(login,name) VALUES('jdoe','John DOE');

// Single line comment style 2

// Single line comment style 3

/**
 Multi line
 comments
 **/
Insert into users(login,name) vAlues('hsue','Helen SUE');

语法验证

解释器附带了一个内置的语法验证器。此验证器仅检查基本的语法错误。

所有与CQL相关的语法验证都直接委托给Cassandra

大多数情况下，语法错误是由于语句之间缺少分号或拼写错误引起的。

模式命令

为了使模式发现更容易且更具交互性，支持以下命令：

模式对象（集群、键空间、表、类型、函数和聚合）以表格形式显示。 左上角有一个下拉菜单，用于展开对象详细信息。右上角菜单显示图标图例。

运行时执行参数

有时您希望能够将运行时查询参数传递给您的语句。

这些参数不是CQL规范的一部分，而是特定于解释器的。

以下是所有参数的列表：

某些参数仅接受受限值：

请注意，您不应在每个参数语句的末尾添加分号（;）

一些例子：

CREATE TABLE IF NOT EXISTS spark_demo.ts(
    key int PRIMARY KEY,
    value text
);
TRUNCATE spark_demo.ts;

// Timestamp in the past
@timestamp=10

// Force timestamp directly in the first insert
INSERT INTO spark_demo.ts(key,value) VALUES(1,'first insert') USING TIMESTAMP 100;

// Select some data to make the clock turn
SELECT * FROM spark_demo.albums LIMIT 100;

// Now insert using the timestamp parameter set at the beginning(10)
INSERT INTO spark_demo.ts(key,value) VALUES(1,'second insert');

// Check for the result. You should see 'first insert'
SELECT value FROM spark_demo.ts WHERE key=1;

关于查询参数的一些说明：

1. 许多查询参数可以在同一段落中设置
2. 如果相同的查询参数被多次设置不同的值，解释器只会考虑第一个值
3. 每个查询参数适用于同一段落中的所有CQL语句，除非你使用纯CQL文本覆盖该选项（例如使用USING子句强制时间戳）
4. 每个查询参数相对于CQL语句的顺序无关紧要

运行时格式化参数

有时您希望能够格式化语句的输出。Cassandra 解释器允许将不同的参数指定为段落的本地属性。以下是所有格式化参数的列表：

一些例子：

create table if not exists zep.test_format (
  id int primary key,
  text text,
  date date,
  timestamp timestamp,
  time time,
  double double,
  float float
);

insert into zep.test_format(id, text, date, timestamp, time, double, float)
  values (1, 'text', '2019-01-29', '2020-06-16T23:59:59.123Z', '04:05:00.234', 
  10.0153423453425634653463466346543, 20.0303443); 

%cassandra(outputFormat=human, locale=de_DE, floatPrecision=2, doublePrecision=4, timeFormat=hh:mma, timestampFormat=MM/dd/yy HH:mm, dateFormat="E, d MMM yy", timezone=Etc/GMT+2)
select id, double, float, text, date, time, timestamp from zep.test_format;

将根据设置输出格式化数据，包括德语区域设置：

id  double   float  text  date           time     timestamp
1   10,0153  20,03  text  Di, 29 Jan 19  04:05AM  06/16/20 21:59

当使用 outputFormat=cql 时，数据被格式化为 CQL 字面量：

id double              float       text    date        time                  timestamp
1  10.015342345342564  20.030344  'text'  '2019-01-29' '04:05:00.234000000'  '2020-06-17T01:59:59.123+02:00'

支持预处理语句

出于性能考虑，最好预先准备语句，然后通过提供绑定值来重复使用它们。

此解释器提供了3个命令来处理准备和绑定的语句：

1. @prepare
2. @bind
3. @remove_prepared

示例：

@prepare[statement-name]=...

@bind[statement-name]=’text’, 1223, ’2015-07-30 12:00:01’, null, true, [‘list_item1’, ’list_item2’]

@bind[statement-name-with-no-bound-value]

@remove_prepare[statement-name]

@prepare

你可以使用语法 "@prepare[statement-name]=SELECT..." 来创建一个预编译语句。 statement-name 是必需的，因为解释器会使用 Java 驱动程序准备给定的语句，并将生成的预编译语句保存在一个内部哈希映射中，使用提供的 statement-name 作为搜索键。

请注意，这个内部准备好的语句映射与所有笔记本和所有段落共享，因为Cassandra的解释器只有一个实例。

如果解释器遇到多个 @prepare 用于相同的语句名称 (键)，则只会考虑第一个语句。

示例：

@prepare[select]=SELECT * FROM spark_demo.albums LIMIT ?

@prepare[select]=SELECT * FROM spark_demo.artists LIMIT ?

对于上述示例，预编译语句是 SELECT * FROM spark_demo.albums LIMIT ?。 SELECT * FROM spark_demo.artists LIMIT ? 被忽略，因为预编译语句映射中已经存在一个键为 select 的条目。

在Zeppelin的上下文中，笔记本可以安排定期执行， 因此有必要避免多次重新准备相同的语句（被认为是一种反模式）。

@bind

一旦语句准备好（可能在一个单独的笔记本/段落中），你可以将值绑定到它：

@bind[select_first]=10

对于@bind语句，绑定值不是强制性的。但是，如果您提供绑定值，它们需要符合一些语法：

• 字符串值应包含在单引号之间（'）
• 日期值应包含在单引号（'）之间，并遵循格式（完整列表在文档中）：
  1. yyyy-MM-dd HH:MM:ss
  2. yyyy-MM-dd HH:MM:ss.SSS
  3. yyyy-mm-dd'T'HH:mm:ss.SSSZ
• null 被原样解析
• boolean (true|false) 按原样解析
• 集合值必须遵循标准CQL语法：
  • 列表: ['listitem1', 'listitem2', ...]
  • 集合: {'setitem1', 'setitem2', …}
  • 映射: {'key1': 'val1', 'key2': 'val2', …}
• tuple 值应括在括号内（参见 Tuple CQL 语法）：('text', 123, true)
• udt 值应放在大括号内（参见 UDT CQL 语法）：{streename: 'Beverly Hills', number: 104, zipcode: 90020, state: 'California', …}

可以在批处理中使用@bind语句：

BEGIN BATCH
   @bind[insert_user]='jdoe','John DOE'
   UPDATE users SET age = 27 WHERE login='hsue';
APPLY BATCH;

@remove_prepare

为了避免一个准备好的语句永远留在准备好的语句映射中，你可以使用 @remove_prepare[statement-name] 语法来移除它。 移除一个不存在的准备好的语句不会产生错误。

使用动态表单

与其硬编码你的CQL查询，不如使用[Zeppelin动态表单]语法来注入简单的值或多选表单。

传统的mustache语法（{{ }}）用于绑定输入文本和选择表单仍然受支持，但已被弃用，并将在未来的版本中移除。

旧版 简单参数的语法是：{{input_Label=默认值}}。默认值是必需的，因为第一次执行段落时， 我们在渲染表单之前启动CQL查询，因此至少应提供一个值。

多选参数的语法是：{{input_Label=value1 | value2 | … | valueN }}。默认情况下，第一次执行段落时，CQL查询使用第一个选项。

示例：

#Secondary index on performer style
SELECT name, country, performer
FROM spark_demo.performers
WHERE name='${performer=Sheryl Crow|Doof|Fanfarlo|Los Paranoia}'
AND styles CONTAINS '${style=Rock}';

在上面的例子中，第一个CQL查询将执行performer='Sheryl Crow' AND style='Rock'。 对于后续的查询，您可以直接使用表单更改值。

请注意，我们将${ }块用单引号（'）括起来，因为Cassandra在这里期望一个字符串。 我们也可以使用${style='Rock'}语法，但这次表单上显示的值是'Rock'而不是Rock。

也可以使用动态表单来创建预编译语句：

@bind[select]=='${performer=Sheryl Crow|Doof|Fanfarlo|Los Paranoia}', '${style=Rock}'

共享状态

可以并行执行许多段落。然而，在后端，我们仍然使用同步查询。 异步执行只有在可以在InterpreterResult中返回Future值时才有可能。 这对于Zeppelin项目可能是一个有趣的提议。

最近，Zeppelin 允许你选择解释器的隔离级别（参见 [Interpreter Binding Mode] ）。

长话短说，你有3种可用的绑定方式：

• shared : 所有笔记使用相同的JVM和相同的解释器实例
• scoped : 相同的JVM 但 不同的解释器实例, 每个笔记一个
• isolated: 不同的JVM 运行一个 单个Interpreter实例，每个笔记一个JVM

使用共享绑定，相同的com.datastax.driver.core.Session对象用于所有笔记和段落。 因此，如果您使用USE keyspace_name;语句登录到一个键空间，它将更改所有当前用户的Cassandra解释器的键空间，因为我们只为每个Cassandra解释器实例创建一个com.datastax.driver.core.Session对象。

同样的评论也适用于prepared statement hash map，它由使用相同Cassandra解释器实例的所有用户共享。

当使用scoped绑定时，在同一个JVM中，Zeppelin将创建多个Cassandra解释器实例，因此会有多个com.datastax.driver.core.Session对象。使用此绑定时请注意资源和内存的使用！

isolated 模式是最极端的，它将为每个不同的节点创建尽可能多的 JVM/com.datastax.driver.core.Session 对象。

解释器配置

要配置Cassandra解释器，请转到Interpreter菜单并向下滚动以更改参数。 Cassandra解释器使用的是官方的Datastax Java Driver for Apache Cassandra®，大多数参数用于配置Java驱动程序

以下是解释器支持的配置参数及其默认值。

除了这些参数外，还可以通过将它们添加到解释器配置中来设置其他驱动程序参数。配置键应具有完整形式，并带有datastax-java-driver前缀，如文档中所述。例如，要指定5秒的请求超时，可以使用datastax-java-driver.basic.request.timeout，其值为5 seconds。完整的可用配置选项列表可在文档中查看。额外的选项可能会覆盖由解释器配置参数指定的选项。

变更日志

4.0 (Zeppelin 0.11.2) :

• 重构以使用统一的Java驱动程序4.7 (ZEPPELIN-4378:
  • 配置中的更改是必要的，因为新驱动程序具有不同的架构和配置选项
  • 解释器获得了对DSE特定数据类型和其他扩展的支持
  • 移除了对@retryPolicy的支持，因为驱动程序只附带了一个重试策略
  • 允许指定Java驱动程序的任何配置选项
  • 放弃了对Cassandra 1.2和2.0的支持，因为驱动程序不再支持这些版本
• 添加了对格式化选项的支持，包括解释器和单元格级别

3.1 (Zeppelin 0.11.2) :

• 升级Java驱动至3.7.2 (ZEPPELIN-4331;

3.0 (Zeppelin 0.11.2) :

• 更新文档
• 更新交互式文档
• 添加对二进制协议 V4 的支持
• 实现新的@requestTimeOut运行时选项
• 将Java驱动程序版本升级到3.0.1
• 允许解释器在使用FormType.SIMPLE时以编程方式添加动态表单
• 允许使用默认的Zeppelin语法进行动态表单
• 修复了FallThroughPolicy上的拼写错误
• 在创建动态表单之前，先在AngularObjectRegistry中查找数据
• 添加对ALTER语句的缺失支持

2.0 (Zeppelin 0.11.2) :

• 更新帮助菜单并添加变更日志
• 添加对用户定义函数、用户定义聚合和物化视图的支持
• 将Java驱动程序版本升级到3.0.0-rc1

1.0 (Zeppelin 0.5.5-incubating) :

• 初始版本

错误与联系

如果您遇到此解释器的错误，请创建一个JIRA工单。

Zeppelin 动态表单 解释器绑定模式