From 2eff364e63f7732e4ef52f3be2ff4a4dcaa7ac58 Mon Sep 17 00:00:00 2001 From: Ivan Blinkov Date: Fri, 19 Oct 2018 13:03:34 +0300 Subject: [PATCH] fixes for zh docs (#3423) * CLICKHOUSE-4063: less manual html @ index.md * CLICKHOUSE-4063: recommend markdown="1" in README.md * CLICKHOUSE-4003: manually purge custom.css for now * CLICKHOUSE-4064: expand
before any print (including to pdf) * CLICKHOUSE-3927: rearrange interfaces/formats.md a bit * CLICKHOUSE-3306: add few http headers * Remove copy-paste introduced in #3392 * Hopefully better chinese fonts #3392 * get rid of tabs @ custom.css * Apply comments and patch from #3384 * Add jdbc.md to ToC and some translation, though it still looks badly incomplete * minor punctuation * Add some backlinks to official website from mirrors that just blindly take markdown sources * Do not make fonts extra light * find . -name '*.md' -type f | xargs -I{} perl -pi -e 's//g' {} * find . -name '*.md' -type f | xargs -I{} perl -pi -e 's/ sql/g' {} * Remove outdated stuff from roadmap.md * Not so light font on front page too * Refactor Chinese formats.md to match recent changes in other languages * Update some links on front page * Remove some outdated comment * Add twitter link to front page * More front page links tuning * Add Amsterdam meetup link * Smaller font to avoid second line * Add Amsterdam link to README.md * Proper docs nav translation * Back to 300 font-weight except Chinese * fix docs build * Update Amsterdam link * remove symlinks * more zh punctuation * apply lost comment by @zhang2014 * Apply comments by @zhang2014 from #3417 --- docs/zh/data_types/array.md | 6 +- docs/zh/data_types/datetime.md | 2 +- docs/zh/query_language/create.md | 156 +++++++++++++++++++++++++- docs/zh/query_language/insert_into.md | 69 +++++++++++- 4 files changed, 227 insertions(+), 6 deletions(-) mode change 120000 => 100644 docs/zh/query_language/create.md mode change 120000 => 100644 docs/zh/query_language/insert_into.md diff --git a/docs/zh/data_types/array.md b/docs/zh/data_types/array.md index 0dc89baf3c7..00e07d38be0 100644 --- a/docs/zh/data_types/array.md +++ b/docs/zh/data_types/array.md @@ -4,11 +4,11 @@ 由 `T` 类型元素组成的数组。 -`T` 可以是任意类型，包含数组类型。不推荐使用多维数组，ClickHouse 对多维数组的支持有限。例如，不能存储在 `MergeTree` 表中存储多维数组。 +`T` 可以是任意类型，包含数组类型。 但不推荐使用多维数组，ClickHouse 对多维数组的支持有限。例如，不能存储在 `MergeTree` 表中存储多维数组。 ## 创建数组 -您可以使用一个函数创建数组： +您可以使用array函数来创建数组： ``` array(T) @@ -50,7 +50,7 @@ SELECT ## 使用数据类型 -当动态创建数组时，ClickHouse 自动将参数类型定义为可以存储所有列出的参数的最窄的数据类型。如果存在任何 [NULL](../query_language/syntax.md#null-literal) 或者 [Nullable](nullable.md#data_type-nullable) 类型参数，那么数组元素的类型是 [Nullable](nullable.md#data_type-nullable)。 +ClickHouse会自动检测数组元素,并根据元素计算出存储这些元素最小的数据类型。如果在元素中存在[NULL](../query_language/syntax.md#null-literal)或存在[Nullable](nullable.md#data_type-nullable)类型元素，那么数组的元素类型将会变成[Nullable](nullable.md#data_type-nullable)。 如果 ClickHouse 无法确定数据类型，它将产生异常。当尝试同时创建一个包含字符串和数字的数组时会发生这种情况 (`SELECT array(1, 'a')`)。 diff --git a/docs/zh/data_types/datetime.md b/docs/zh/data_types/datetime.md index 4a5a8095f0a..6988d7da283 100644 --- a/docs/zh/data_types/datetime.md +++ b/docs/zh/data_types/datetime.md @@ -2,7 +2,7 @@ # DateTime -时间戳类型。用四个字节存储 Unix 时间戳（无符号的）。允许存储与日期类型相同的范围内的值。最小值为 0000-00-00 00:00:00。时间戳类型值精确到秒（没有闰秒）。 +时间戳类型。用四个字节（无符号的）存储 Unix 时间戳）。允许存储与日期类型相同的范围内的值。最小值为 0000-00-00 00:00:00。时间戳类型值精确到秒（没有闰秒）。 ## 时区 diff --git a/docs/zh/query_language/create.md b/docs/zh/query_language/create.md deleted file mode 120000 index a13304d176e..00000000000 --- a/docs/zh/query_language/create.md +++ /dev/null @@ -1 +0,0 @@ -../../en/query_language/create.md \ No newline at end of file diff --git a/docs/zh/query_language/create.md b/docs/zh/query_language/create.md new file mode 100644 index 00000000000..d554dfeeb5b --- /dev/null +++ b/docs/zh/query_language/create.md @@ -0,0 +1,155 @@ +## 创建数据库 + +创建 `db_name` 数据库。 + +```sql +CREATE DATABASE [IF NOT EXISTS] db_name +``` + +数据库是一个包含多个表的目录，如果在CREATE DATABASE语句中包含`IF NOT EXISTS`，则在数据库已经存在的情况下查询也不会返回错误。 + + + +## 创建表 + +`CREATE TABLE` 语句有几种形式. + +```sql +CREATE [TEMPORARY] TABLE [IF NOT EXISTS] [db.]name [ON CLUSTER cluster] +( + name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1]， + name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2]， + ... +) ENGINE = engine +``` + +如果`db`没有设置， 在数据库`db`中或者当前数据库中， 创建一个表名为`name`的表， 在括号和`engine` 引擎中指定结构。 表的结构是一个列描述的列表。 如果引擎支持索引， 则他们将是表引擎的参数。 + +表结构是一个列描述的列表。 如果引擎支持索引， 他们以表引擎的参数表示。 + +在最简单的情况， 一个列描述是'命名类型'。 例如: RegionID UInt32。 对于默认值， 表达式也能够被定义。 + +```sql +CREATE [TEMPORARY] TABLE [IF NOT EXISTS] [db.]name AS [db2.]name2 [ENGINE = engine] +``` + +创建一个表， 其结构与另一个表相同。 你能够为此表指定一个不同的引擎。 如果引擎没有被指定， 相同的引擎将被用于`db2。name2`表上。 + +```sql +CREATE [TEMPORARY] TABLE [IF NOT EXISTS] [db.]name ENGINE = engine AS SELECT ... +``` + +创建一个表，其结构类似于 SELECT 查询后的结果， 带有`engine` 引擎， 从 SELECT查询数据填充它。 + +在所有情况下，如果`IF NOT EXISTS`被指定， 如果表已经存在， 查询并不返回一个错误。 在这种情况下， 查询并不做任何事情。 + +### 默认值 + +列描述能够为默认值指定一个表达式， 其中一个方法是:DEFAULT expr， MATERIALIZED expr， ALIAS expr。 +例如: URLDomain String DEFAULT domain(URL)。 + +如果默认值的一个表达式没有定义， 如果字段是数字类型， 默认值是将设置为0， 如果是字符类型， 则设置为空字符串， 日期类型则设置为 0000-00-00 或者 0000-00-00 00:00:00(时间戳)。 NULLs 则不支持。 + +如果默认表达式被定义， 字段类型是可选的。 如果没有明确的定义类型， 则将使用默认表达式。 例如: EventDate DEFAULT toDate(EventTime) – `Date` 类型将用于 `EventDate` 字段。 + +如果数据类型和默认表达式被明确定义， 此表达式将使用函数被转换为特定的类型。 例如: Hits UInt32 DEFAULT 0 与 Hits UInt32 DEFAULT toUInt32(0)是等价的。 + +默认表达是可能被定义为一个任意的表达式，如表的常量和字段。 当创建和更改表结构时， 它将检查表达式是否包含循环。 对于 INSERT操作来说， 它将检查表达式是否可解析 – 所有的字段通过传参后进行计算。 + +`DEFAULT expr` + +正常的默认值。 如果 INSERT 查询并没有指定对应的字段， 它将通过计算对应的表达式来填充。 + +`物化表达式` + +物化表达式。 此类型字段并没有指定插入操作， 因为它经常执行计算任务。 对一个插入操作， 无字段列表， 那么这些字段将不考虑。 另外， 当在一个SELECT查询语句中使用星号时， 此字段并不被替换。 这将保证INSERT INTO SELECT * FROM 的不可变性。 + +`别名表达式` + +别名。 此字段不存储在表中。 +此列的值不插入到表中， 当在一个SELECT查询语句中使用星号时，此字段并不被替换。 +它能够用在 SELECTs中，如果别名在查询解析时被扩展。 + +当使用更新查询添加一个新的字段， 这些列的旧值不被写入。 相反， 新字段没有值，当读取旧值时， 表达式将被计算。 然而，如果运行表达式需要不同的字段， 这些字段将被读取 ， 但是仅读取相关的数据块。 + +如果你添加一个新的字段到表中， 然后改变它的默认表达式， 对于使用的旧值将更改(对于此数据， 值不保存在磁盘上)。 当运行背景线程时， 缺少合并数据块的字段数据写入到合并数据块中。 + +在嵌套数据结构中设置默认值是不允许的。 + + +### 临时表 + +在任何情况下， 如果临时表被指定， 一个临时表将被创建。 临时表有如下的特性: + +- 当会话结束后， 临时表将删除，或者连接丢失。 +- 一个临时表使用内存表引擎创建。 其他的表引擎不支持临时表。 +- 数据库不能为一个临时表指定。 它将创建在数据库之外。 +- 如果一个临时表与另外的表有相同的名称 ，一个查询指定了表名并没有指定数据库， 将使用临时表。 +- 对于分布式查询处理， 查询中的临时表将被传递给远程服务器。 + +在大多数情况下， 临时表并不能手工创建， 但当查询外部数据或使用分布式全局(GLOBAL)IN时，可以创建临时表。 + +分布式 DDL 查询 (ON CLUSTER clause) +---------------------------------------------- + +`CREATE`， `DROP`， `ALTER`， 和 `RENAME` 查询支持在集群上分布式执行。 例如， 如下的查询在集群中的每个机器节点上创建了 all_hits Distributed 表: + +```sql +CREATE TABLE IF NOT EXISTS all_hits ON CLUSTER cluster (p Date， i Int32) ENGINE = Distributed(cluster， default， hits) +``` + +为了正确执行这些语句，每个节点必须有相同的集群设置(为了简化同步配置，可以使用 zookeeper 来替换)。 这些节点也可以连接到ZooKeeper 服务器。 +查询语句会在每个节点上执行， 而`ALTER`查询目前暂不支持在同步表(replicated table)上执行。 + + + +## CREATE VIEW + +```sql +CREATE [MATERIALIZED] VIEW [IF NOT EXISTS] [db.]name [TO[db.]name] [ENGINE = engine] [POPULATE] AS SELECT ... +``` + +创建一个视图。 有两种类型的视图: 正常视图和物化(MATERIALIZED)视图。 + +当创建一个物化视图时， 你必须指定表引擎 – 此表引擎用于存储数据 + +一个物化视图工作流程如下所示: 当插入数据到SELECT 查询指定的表中时， 插入数据部分通过SELECT查询部分来转换， 结果插入到视图中。 + +正常视图不保存任何数据， 但是可以从任意表中读取数据。 换句话说，正常视图可以看作是查询结果的一个结果缓存。 当从一个视图中读取数据时， 此查询可以看做是 FROM语句的子查询。 + +例如， 假设你已经创建了一个视图: + +```sql +CREATE VIEW view AS SELECT ... +``` + +写了一个查询语句: + +```sql +SELECT a, b, c FROM view +``` +此查询完全等价于子查询: + +```sql +SELECT a, b, c FROM (SELECT ...) +``` + +物化视图保存由SELECT语句查询转换的数据。 + +当创建一个物化视图时，你必须指定一个引擎 – 存储数据的目标引擎。 + +一个物化视图使用流程如下: 当插入数据到 SELECT 指定的表时， 插入数据部分通过SELECT 来转换， 同时结果被插入到视图中。 + + +如果你指定了 POPULATE， 当创建时， 现有的表数据被插入到了视图中， 类似于 `CREATE TABLE ... AS SELECT ...` . 否则， 在创建视图之后，查询仅包含表中插入的数据. 我们不建议使用 POPULATE， 在视图创建过程中，插入到表中的数据不插入到其中. + +一个`SELECT`查询可以包含 `DISTINCT`， `GROUP BY`， `ORDER BY`， `LIMIT`。。。 对应的转换在每个数据块上独立执行。 例如， 如果 GROUP BY 被设置， 数据将在插入过程中进行聚合， 但仅是在一个插入数据包中。数据不再进一步聚合。 当使用一个引擎时， 如SummingMergeTree，它将独立执行数据聚合。 + +视图看起来和正常表相同。 例如， 你可以使用 SHOW TABLES来列出视图表的相关信息。 + +物化视图的`ALTER`查询执行还没有完全开发出来， 因此使用上可能不方便。 如果物化视图使用 `TO [db。]name`， 你能够 `DETACH` 视图， 在目标表运行 `ALTER`， 然后 `ATTACH` 之前的 `DETACH`视图。 + +视图看起来和正常表相同。 例如， 你可以使用 `SHOW TABLES` 来列出视图表的相关信息。 + +因此并没有一个单独的SQL语句来删除视图。 为了删除一个视图， 可以使用 `DROP TABLE`。 + diff --git a/docs/zh/query_language/insert_into.md b/docs/zh/query_language/insert_into.md deleted file mode 120000 index 29b47662b0d..00000000000 --- a/docs/zh/query_language/insert_into.md +++ /dev/null @@ -1 +0,0 @@ -../../en/query_language/insert_into.md \ No newline at end of file diff --git a/docs/zh/query_language/insert_into.md b/docs/zh/query_language/insert_into.md new file mode 100644 index 00000000000..7bea8a0b361 --- /dev/null +++ b/docs/zh/query_language/insert_into.md @@ -0,0 +1,68 @@ + + +## INSERT + +正在添加数据。 + +基本查询格式: + +```sql +INSERT INTO [db.]table [(c1, c2, c3)] VALUES (v11, v12, v13), (v21, v22, v23), ... +``` + +此查询能够指定字段的列表来插入 `[(c1, c2, c3)]`。 在这种情况下, 剩下的字段用如下来填充: + +- 从表定义中指定的 `DEFAULT` 表达式中计算出值。 +- 空字符串， 如果 `DEFAULT` 表达式没有定义。 + +如果 [strict_insert_defaults=1](../operations/settings/settings.md#settings-strict_insert_defaults)， 没有 `DEFAULT` 定义的字段必须在查询中列出. + +在任何ClickHouse所支持的格式上 [format](../interfaces/formats.md#formats) 数据被传入到 INSERT中. 此格式必须被显式地指定在查询中: + +```sql +INSERT INTO [db.]table [(c1， c2， c3)] FORMAT format_name data_set +``` + +例如， 如下的查询格式与基本的 `INSERT ... VALUES` 版本相同: + +```sql +INSERT INTO [db.]table [(c1, c2, c3)] FORMAT Values (v11, v12, v13), (v21, v22, v23), ... +``` + +ClickHouse 在数据之前， 删除所有空格和换行(如果有)。 当形成一个查询时， 我们推荐在查询操作符之后将数据放入新行(如果数据以空格开始， 这是重要的)。 + +示例: + +```sql +INSERT INTO t FORMAT TabSeparated +11 Hello, world! +22 Qwerty +``` + +你能够单独从查询中插入数据，通过命令行或 HTTP 接口. 进一步信息， 参见 "[Interfaces](../interfaces/index.md#interfaces)". + +### Inserting The Results of `SELECT` + +```sql +INSERT INTO [db.]table [(c1, c2, c3)] SELECT ... +``` + +在 SELECT语句中， 根据字段的位置来映射。 然而， 在SELECT表达式中的名称和表名可能不同。 如果必要， 可以进行类型转换。 + +除了值以外没有其他数据类型允许设置值到表达式中， 例如 `now()`， `1 + 2`， 等。 值格式允许使用有限制的表达式， 但是它并不推荐， 因为在这种情况下， 执行了低效的代码。 + +不支持修改数据分区的查询如下: `UPDATE`， `DELETE`， `REPLACE`， `MERGE`， `UPSERT`， `INSERT UPDATE`。 +然而， 你能够使用 `ALTER TABLE ... DROP PARTITION`来删除旧数据。 + +### Performance Considerations + +`INSERT` 通过主键来排序数据， 并通过月份来拆分数据到每个分区中。 如果插入的数据有混合的月份， 会显著降低`INSERT` 插入的性能。 应该避免此类操作: + +- 大批量地添加数据， 如每次 100，000 行。 +- 在上传数据之前， 通过月份分组数据。 + +下面操作性能不会下降: + +- 数据实时插入。 +- 上传的数据通过时间来排序。 +