连接StarRocks #

StarRocks 兼容 MySQL 协议，您可以直接通过 MySQL 客户端按照如下格式连接 StarRocks 服务：

mysql -h {fe_node_ip} -P {fe_query_port} -u {username} -p;

参数说明：

• fe_node_ip：StarRocks 任意 FE 节点 IP，可以是内网 IP 或公网 IP。
• fe_query_port：StarRocks MySQL Server 端口，您可以在控制台通过集群详情页通过访问“服务列表 - StarRocks - 服务参数”中的 query_port 配置项获取，默认为 9030。

首次连接可以直接使用 root 账户登录，示例：

# 首次连接需输入root初始密码
$ mysql -h 127.0.0.1 -P 9030 -u root -p;

root 密码已经初始化好，可以在控制台 服务管理 - StarRocks - 服务参数 中搜索 decrypted_sre_password，查看初始化密码。如果有需求可以自行修改。

用户和权限管理 #

对于具备 user_admin 管理员权限的用户（例如 root 用户），可以对集群的用户和权限进行更加细粒度的管理，以保证数据的安全性。

用户管理 #

• 创建用户

您可以通过如下 SQL 语法创建用户：

CREATE USER 
-- 用户标识，由用户名和登录 IP 组成，例如 zhangsan@'127.0.0.1'
{user_identity}
-- 用户认证方式，支持原生密码、mysql_native_password 和 LDAP 三种认证方式
[auth_option]
-- 为用户绑定权限角色，从而授予相应的操作权限
[DEFAULT ROLE {role_name}[, {role_name}, ...]]

示例：

mysql> CREATE USER username@'%' IDENTIFIED BY '***' DEFAULT ROLE db_admin, user_admin;

• 查看用户

您可以通过 SHOW USERS 查看当前集群中所有的用户，示例：

mysql> SHOW USERS;
+-------------------------+
| User                    |
+-------------------------+
| 'root'@'%'              |
| 'username'@'%'          |
| 'emr'@'127.0.0.1'       |
+-------------------------+

• 修改用户

您可以通过如下 SQL 语法修改指定用户的信息，例如用户密码、认证方式，以及权限角色等：

ALTER USER 
-- 用户标识，由用户名和登录 IP 组成，例如 zhangsan@'127.0.0.1'
user_identity 
-- 用户认证方式，支持原生密码、mysql_native_password 和 LDAP 三种认证方式
[auth_option] 
-- 为用户绑定权限角色，从而授予相应的操作权限
[default_role]

如下示例演示了修改指定用户的密码信息：

mysql> ALTER USER 'username'@'%' IDENTIFIED BY '***';

• 删除用户

您可以通过 DROP USER 删除指定的用户，示例：

mysql> DROP USER 'username'@'%';

权限管理 #

StarRocks 内置提供了一套基于 RBAC 的权限管理策略，您可以通过执行 SHOW ROLES 查看集群已有的权限角色。关于角色的管理可以参考 StarRocks 官方说明。

• 权限授予

通过 GRANT 操作给用户关联某个角色可以实现将角色对应的权限授予给用户，例如给用户关联 db_admin 角色：

mysql> GRANT db_admin TO USER 'username'@'%';

您也可以绕过角色，直接给用户赋予具体权限。如下示例演示了直接给用户赋予 tb_primary_key 表的 SELECT 权限：

mysql> GRANT SELECT ON TABLE tb_primary_key TO USER 'username'@'%' WITH GRANT OPTION;

您可以通过 SHOW GRANTS 查看当前用户或指定用户的权限授予情况：

mysql> SHOW GRANTS FOR 'username'@'%' \G;
*************************** 1. row ***************************
UserIdentity: 'username'@'%'
     Catalog: NULL
      Grants: GRANT 'db_admin' TO 'username'@'%'
*************************** 2. row ***************************
UserIdentity: 'username'@'%'
     Catalog: default_catalog
      Grants: GRANT SELECT ON TABLE examples.tb_primary_key TO USER 'username'@'%' WITH GRANT OPTION

• 权限撤销

您可以通过 REVOKE 操作撤销指定用户或角色的权限。例如撤销用户对于表 tb_primary_key 的 SELECT 权限：

mysql> REVOKE SELECT ON TABLE tb_primary_key FROM USER 'username'@'%';

库表管理 #

数据库管理 #

通过 MySQL 协议连接到 StarRocks 服务后，您可以通过 SQL 语句实现对于数据库和数据表的查看和管理操作。

• 创建数据库

您可以通过如下 SQL 语法操作创建数据库：

CREATE DATABASE [IF NOT EXISTS] {db_name}

参数 db_name 表示数据库名称，命名规则可以参考 StarRocks 官方说明文档。如下示例演示创建一个名为 examples 的数据库：

mysql> CREATE DATABASE IF NOT EXISTS examples;

• 查看数据库

您可以通过如下 SQL 语法查看指定 Catalog 下已创建的数据库：

SHOW DATABASES [FROM {catalog_name}]

参数 catalog_name 表示 Catalog 名称，如果不指定则默认为 default_catalog。如下示例演示查看位于 default_catalog 中的数据库：

mysql> SHOW DATABASES;
+--------------------+
| Database           |
+--------------------+
| _statistics_       |
| examples           |
| information_schema |
| sys                |
+--------------------+

您也可以通过如下 SQL 语法查看指定数据库的创建语句：

SHOW CREATE DATABASE {db_name}

示例：

mysql> SHOW CREATE DATABASE examples;
+----------+----------------------------+
| Database | Create Database            |
+----------+----------------------------+
| examples | CREATE DATABASE `examples` |
+----------+----------------------------+

• 更新数据库

您可以通过如下 SQL 语法实现对于数据库的重命名、Quota 设置：

-- 重命名数据库
ALTER DATABASE {db_name} RENAME {new_db_name}

-- 设置数据库数据量 Quota，单位为 B/K/KB/M/MB/G/GB/T/TB/P/PB
ALTER DATABASE {db_name} SET DATA QUOTA {quota}

-- 设置数据库副本数量 Quota
ALTER DATABASE {db_name} SET REPLICA QUOTA {quota}

如下示例演示了将数据库 examples 重命名为 demo：

mysql> ALTER DATABASE examples RENAME demo;

• 删除数据库

您可以通过如下 SQL 语法实现删除指定数据库：

DROP DATABASE [IF EXISTS] {db_name} [FORCE]

示例：

mysql> DROP DATABASE demo;

说明：

• 执行 DROP DATABASE 后，默认 1 天内可以通过 RECOVER 语句恢复被删除的数据库，但是该数据库下已经随数据库删除的 Pipe 导入作业无法恢复。
• 如果执行 DROP DATABASE FORCE，则系统不会检查该数据库是否存在未完成的事务，数据库将直接被删除并且不能被恢复，一般不建议执行此操作。

数据表管理 #

• 创建数据表

您可以通过 CREATE TABLE 语句在指定数据库下创建数据表，典型的 SQL 语法如下：

CREATE [EXTERNAL] TABLE [IF NOT EXISTS] [{database_name}.]{table_name}
(
    -- 列定义
    column_definition1[, column_definition2, ...]
    -- 索引定义
    [index_definition1[, index_definition2, ...]]
)
-- 引擎定义，默认为 OLAP，表示内部表，还支持外部表，包括 mysql、elasticsearch、hive、jdbc、hudi、iceberg...
[ENGINE = OLAP]
-- 定义数据模型和排序键，默认为明细模型
[key_desc]
-- 定义表的描述信息
[COMMENT '这里是表的描述信息']
-- 定义表的分区方式，支持表达式分区、Range 分区和 List 分区
[partition_desc]
-- 定义数据分桶方式，支持随机分桶和哈希分桶
[distribution_desc]
-- 对于主键模型，可以通过 ORDER BY 独立设置排序键
[ORDER BY (column_definition1,...)]
-- 设置表的属性配置，例如副本数
[PROPERTIES ("key"="value", ...)]

您可以访问 StarRocks 官方说明文档 了解各个参数的详细说明。如下示例演示了在 examples 数据库下创建名为 tb_primary_key 的主键表：

mysql> USE examples;
Database changed

mysql> CREATE TABLE IF NOT EXISTS tb_primary_key
    -> (
    ->     user_id BIGINT       NOT NULL COMMENT 'user id',
    ->     name    VARCHAR(32)  NOT NULL COMMENT 'user name',
    ->     age     TINYINT      NOT NULL COMMENT 'user age',
    ->     sex     TINYINT      NOT NULL COMMENT 'user sex',
    ->     email   VARCHAR(256) NULL COMMENT 'email'
    -> ) ENGINE = OLAP PRIMARY KEY (user_id)
    -> DISTRIBUTED BY HASH(user_id)
    -> ORDER BY(`name`)
    -> PROPERTIES (
    ->     'replication_num' = '3'
    -> );

您也可以通过 CREATE TABLE AS SELECT 语法查询原表，并基于查询结果创建新表；通过 CREATE TABLE LIKE 语法基于已有的表结构创建新表。

• 查看数据表

您可以通过如下 SQL 语法查看位于指定数据库下的数据表：

SHOW TABLES [FROM {catalog_name}.{db_name}]

其中参数 catalog_name 表示 Catalog 名称，如果不指定则默认为 default_catalog；参数 db_name 表述数据库名称，如果不指定则默认为当前数据库。示例：

mysql> SHOW TABLES;
+--------------------+
| Tables_in_examples |
+--------------------+
| tb_primary_key     |
+--------------------+

您也可以通过如下 SQL 语法查看指定数据表的创建语句：

SHOW CREATE TABLE [{db_name}.]{table_name}

示例：

mysql> SHOW CREATE TABLE tb_primary_key \G;
*************************** 1. row ***************************
       Table: tb_primary_key
Create Table: CREATE TABLE `tb_primary_key` (
  `user_id` bigint(20) NOT NULL COMMENT "user id",
  `name` varchar(32) NOT NULL COMMENT "user name",
  `age` tinyint(4) NOT NULL COMMENT "user age",
  `sex` tinyint(4) NOT NULL COMMENT "user sex",
  `email` varchar(256) NULL COMMENT "email"
) ENGINE=OLAP
PRIMARY KEY(`user_id`)
DISTRIBUTED BY HASH(`user_id`)
ORDER BY(`name`)
PROPERTIES (
"replication_num" = "3",
"in_memory" = "false",
"enable_persistent_index" = "true",
"replicated_storage" = "true",
"compression" = "LZ4"
);

• 更新数据表

您可以通过如下 SQL 语法对指定的数据表进行修改：

ALTER TABLE [{db_name}.]{tbl_name}
alter_clause1[, alter_clause2, ...]

其中 alter_clause 表示具体的修改操作，目前支持的操作如下表所示：

如下示例演示了修改数据表的注释信息：

mysql> ALTER TABLE tb_primary_key COMMENT='这里是新的描述信息';

您可以通过 SHOW ALTER TABLE 查看 ALTER 任务的执行情况。

• 删除数据表

您可以通过如下 SQL 语法操作删除指定的数据表：

DROP TABLE [IF EXISTS] [{db_name}.]{table_name} [FORCE]

示例：

mysql> DROP TABLE tb_primary_key;

说明：

• 执行 DROP TABLE 后，默认 1 天内可以通过 RECOVER 语句恢复被删除的数据表。
• 如果执行 DROP TABLE FORCE，则系统不会检查该表是否存在未完成的事务，数据表将直接被删除并且不能被恢复，一般不建议执行此操作。

数据查询 #

通过 MySQL 协议连接到 StarRocks 服务后，您可以通过 SQL 语句实现对于 StarRocks 中数据的查询、更新，以及删除操作。

• 插入数据

您可以通过 INSERT 语句向指定数据表中插入数据，典型的 SQL 语法如下：

INSERT { INTO | OVERWRITE } [{db_name}.]{table_name}
-- 指定插入分区
[ PARTITION ({partition_name} [, ...] ) ]
-- 插入的数据值
{ VALUES ( { {expression} | DEFAULT } [, ...] ) | {query} }

示例：

mysql> INSERT INTO tb_primary_key
    -> VALUES (10001, 'aaaa', 26, 1, 'aaaa@starrocks.com'),
    ->        (10002, 'bbbb', 17, 0, 'bbbb@starrocks.com'),
    ->        (10001, 'aaaa', 27, 1, 'aaaa@starrocks.com'),
    ->        (10001, 'aaaa', 28, 1, 'aaaa@starrocks.com');
{'label':'insert_42bd9455-dd1b-11ee-9417-00163e11548e', 'status':'VISIBLE', 'txnId':'2'}

• 查询数据

您可以通过 SELECT 语句查询指定数据表中的数据，典型的 SQL 语法如下：

SELECT ...
FROM ...
[ ... ]
GROUP BY [
    , ... |
    GROUPING SETS [, ...] (  groupSet [ , groupSet [ , ... ] ] ) |
    ROLLUP(expr  [ , expr [ , ... ] ]) |
    CUBE(expr  [ , expr [ , ... ] ])
    ]
[ ... ]

示例：

mysql> SELECT * FROM tb_primary_key;
+---------+------+------+------+--------------------+
| user_id | name | age  | sex  | email              |
+---------+------+------+------+--------------------+
|   10002 | bbbb |   17 |    0 | bbbb@starrocks.com |
|   10001 | aaaa |   28 |    1 | aaaa@starrocks.com |
+---------+------+------+------+--------------------+

• 删除数据

您可以通过 DELETE 语句删除指定数据表中满足条件的数据，典型的 SQL 语法如下：

DELETE FROM [{db_name}.]{table_name} [PARTITION {partition_name}]
WHERE
-- 设置删除过滤条件，可以指定一个或多个列，在同时满足条件时实施删除操作
column_name1 op { value | value_list } [ AND column_name2 op { value | value_list } ...]

示例：

mysql> DELETE FROM tb_primary_key WHERE user_id = 10001;
{'label':'delete_3f0f15e5-dd1c-11ee-9417-00163e11548e', 'status':'VISIBLE', 'txnId':'4'}

#