Merge pull request #411 from sizhitu/master

doc: update json.sgml等

Author: ChenHuajun

postgresql/doc/src/sgml/json.sgml

@@ -127,7 +127,7 @@ ____________________________________________________________________________-->
  </para>
 ____________________________________________________________________________-->
  <para>
-  RFC 7159 指定 JSON 字符串应以 UTF8 编码。因此 JSON 类型不可能严格遵守 JSON 规范，除非数据库编码
+  <acronym>RFC</acronym> 7159 指定 JSON 字符串应以 UTF8 编码。因此 JSON 类型不可能严格遵守 JSON 规范，除非数据库编码
   是 UTF8。尝试直接包括数据库编码中无法表示的字符将会失败。反过来，能
   在数据库编码中表示但是不在 UTF8 中的字符是被允许的。
  </para>
@@ -151,7 +151,7 @@ ____________________________________________________________________________-->
  </para>
 ____________________________________________________________________________-->
  <para>
-  RFC 7159 允许 JSON 字符串包含<literal>\u<replaceable>XXXX</replaceable></literal>
+  <acronym>RFC</acronym> 7159 允许 JSON 字符串包含<literal>\u<replaceable>XXXX</replaceable></literal>
   所标记的 Unicode 转义序列。在<type>json</type>类型的输入函数中，不管数据库
   编码如何都允许 Unicode 转义，并且只检查语法正确性（即，跟在<literal>\u</literal>
   后面的四个十六进制位）。但是，<type>jsonb</type>的输入函数更加严格：它不允许对无法在数据库
@@ -956,7 +956,7 @@ ____________________________________________________________________________-->
 SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
 </programlisting>
 <programlisting>
-SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @? '$.tags[*] ? (@ == "qui")';
+SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] ? (@ == "qui")';
 </programlisting>
     GIN 索引从<literal>jsonpath</literal>中提取如下格式的语句： <replaceable>accessors_chain</replaceable> = <replaceable>const</replaceable>。
     存取器链可能由<literal>.key</literal><literal>[*]</literal>, 和 <literal>[<replaceable>index</replaceable>]</literal> 存取器组成。
@@ -1152,6 +1152,78 @@ ____________________________________________________________________________-->
   </para>
  </sect2>
 
+ <sect2 id="jsonb-subscripting">
+  <title><type>jsonb</type> 下标</title>
+  <para>
+   <type>jsonb</type> 数据类型支持用于检索和修改元素的数组样式索引。 嵌套值与 <literal>jsonb_set</literal> 函数中<literal>path</literal>参数规则相同，可以被链式下标表达式指定。如果<type>jsonb</type>
+   类型的值是一个数组，数值下标从零开始，负整数从数组的最后的元素倒数。 不支持切片表达式。下标表达式的结果始终是 jsonb 数据类型。
+  </para>
+
+  <para>
+   <command>UPDATE</command> 语句或许在
+   <literal>SET</literal> 子句中使用下标来修改 <type>jsonb</type> 值。下标路径必须对它存在范围内的所有受影响的值都是可遍历的。 例如，<literal>val</literal>,<literal>val['a']</literal>,和 <literal>val['a']['b']</literal>如果每个路径都是一个对象，  则<literal>val['a']['b']['c']</literal>路径可以一直被遍历访问到 <literal>c</literal>， 如果 <literal>val['a']</literal> 或者 <literal>val['a']['b']</literal>
+   中任何一个没有定义， 将创建为空对象并根据需要进行填充。 但是， 如果 <literal>val</literal> 本身或者其中任何一个中间值被定义为非对象， 例如 字符串， 数字，或者<literal>jsonb</literal> <literal>null</literal>等，将无法访问并发生错误，事务将中止。
+  </para>
+
+  <para>
+   下标语法的例子:
+
+<programlisting>
+
+-- -- 通过键获取对象值
+SELECT ('{"a": 1}'::jsonb)['a'];
+
+--  通过键路径提取嵌套对象的值
+SELECT ('{"a": {"b": {"c": 1}}}'::jsonb)['a']['b']['c'];
+
+-- 通过索引获取数组元素
+SELECT ('[1, "2", null]'::jsonb)[1];
+
+-- 按键更新对象值。请注意“1”周围的单引号。
+-- 赋值的值也必须是jsonb类型
+UPDATE table_name SET jsonb_field['key'] = '1';
+
+--  如果 jsonb_field['a']['b'] 中的任何数据不是对象，这将导致错误。
+-- 例如，值 {"a": 1} 具有键 'a' 的数值。
+UPDATE table_name SET jsonb_field['a']['b']['c'] = '1';
+
+-- 在 WHERE 子句中使用下标过滤数据。
+-- 由于下标的结果是jsonb，所以要与之比较的值也一定是jsonb。
+-- 双引号还使“值”成为有效的 jsonb 字符串。
+SELECT * FROM table_name WHERE jsonb_field['key'] = '"value"';
+</programlisting>
+
+   <type>jsonb</type>不同于 <literal>jsonb_set</literal>，通过下标赋值处理边界情况. 当源值 <type>jsonb</type>
+   是 <literal>NULL</literal>时, 赋值通过下标处理，
+   好像是空JSON值 类型（对象或数组）隐含在下标键中：
+
+<programlisting>
+-- 如果 jsonb_field 为 NULL，返回结果将是 {"a": 1}
+UPDATE table_name SET jsonb_field['a'] = '1';
+
+-- 如果 jsonb_field 为 NULL，返回结果将是 [1]
+UPDATE table_name SET jsonb_field[0] = '1';
+</programlisting>
+   如果您为缺少元素的数组指定索引，则会添加<literal>NULL</literal> 元素， 直到索引可达并且可以设置值。
+<programlisting>
+-- 如果 jsonb_field 是 [] 返回结果是 [null, null, 2],
+-- 如果 jsonb_field 是 [0]，返回结果是 [0, null, 2]
+UPDATE table_name SET jsonb_field[2] = '2';
+</programlisting>
+
+   <type>jsonb</type> 值接受赋值给不存在的下标路径，只要最后一个可以被访问到的元素是一个对象或者数组 ，正如相应的下标所暗示的那样。（没有访问到路径中最后一个下标指定的元素，可能是任何值）创建嵌套数组或对象结构，如在前面的例子中，指定的下标路径用 <literal>null</literal>填充
+
+<programlisting>
+-- 如果 jsonb_field 是 {}，返回结果是 {"a": [{"b": 1}]}
+UPDATE table_name SET jsonb_field['a'][0]['b'] = '1';
+
+-- 如果 jsonb_field 为 []，返回结果是 [null, {"a": 1}]
+UPDATE table_name SET jsonb_field[1]['a'] = '1';
+</programlisting>
+
+  </para>
+ </sect2>
+
  <sect2>
 <!--==========================orignal english content==========================
   <title>Transforms</title>

postgresql/doc/src/sgml/logical-replication.sgml

@@ -224,7 +224,7 @@ ____________________________________________________________________________-->
    fallback if no other solution is possible.  If a replica identity other
    than <quote>full</quote> is set on the publisher side, a replica identity
    comprising the same or fewer columns must also be set on the subscriber
-   side.  See <xref linkend="sql-createtable-replica-identity"/> for details on
+   side.  See <xref linkend="sql-altertable-replica-identity"/> for details on
    how to set the replica identity.  If a table without a replica identity is
    added to a publication that replicates <command>UPDATE</command>
    or <command>DELETE</command> operations then
@@ -234,7 +234,7 @@ ____________________________________________________________________________-->
   </para>
 ____________________________________________________________________________-->
   <para>
-   为了能够复制<command>UPDATE</command>和<command>DELETE</command>操作，被发布的表必须配置有一个<quote>复制标识</quote>，这样在订阅者那一端才能标识对于更新或删除合适的行。默认情况下，复制标识就是主键（如果有主键）。也可以在复制标识上设置另一个唯一索引（有特定的额外要求）。如果表没有合适的键，那么可以设置成复制标识<quote>full</quote>，它表示整个行都成为那个键。不过，这样做效率很低，只有在没有其他方案的情况下才应该使用。如果在发布者端设置了<quote>full</quote>之外的复制标识，在订阅者端也必须设置一个复制标识，它应该由相同的或者少一些的列组成。如何设置复制标识的细节请参考<xref linkend="sql-createtable-replica-identity"/>。如果在复制<command>UPDATE</command>或<command>DELETE</command>操作的发布中加入了没有复制标识的表，那么订阅者上后续的<command>UPDATE</command>或<command>DELETE</command>操作将导致错误。不管有没有复制标识，<command>INSERT</command>操作都能继续下去。
+   为了能够复制<command>UPDATE</command>和<command>DELETE</command>操作，被发布的表必须配置有一个<quote>复制标识</quote>，这样在订阅者那一端才能标识对于更新或删除合适的行。默认情况下，复制标识就是主键（如果有主键）。也可以在复制标识上设置另一个唯一索引（有特定的额外要求）。如果表没有合适的键，那么可以设置成复制标识<quote>full</quote>，它表示整个行都成为那个键。不过，这样做效率很低，只有在没有其他方案的情况下才应该使用。如果在发布者端设置了<quote>full</quote>之外的复制标识，在订阅者端也必须设置一个复制标识，它应该由相同的或者少一些的列组成。如何设置复制标识的细节请参考<xref linkend="sql-altertable-replica-identity"/>。如果在复制<command>UPDATE</command>或<command>DELETE</command>操作的发布中加入了没有复制标识的表，那么订阅者上后续的<command>UPDATE</command>或<command>DELETE</command>操作将导致错误。不管有没有复制标识，<command>INSERT</command>操作都能继续下去。
   </para>
 
 <!--==========================orignal english content==========================
@@ -253,7 +253,7 @@ ____________________________________________________________________________-->
   </para>
 ____________________________________________________________________________-->
   <para>
-   Publication通过使用<xref linkend="sql-createpublication"/>命令创建并且可以在之后使用相应的命令进行修改或者删除。
+   Publication通过使用<link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>命令创建并且可以在之后使用相应的命令进行修改或者删除。
   </para>
 
 <!--==========================orignal english content==========================
@@ -266,7 +266,7 @@ ____________________________________________________________________________-->
   </para>
 ____________________________________________________________________________-->
   <para>
-   表可以使用<xref linkend="sql-alterpublication"/>动态地增加或者移除。<literal>ADD TABLE</literal>以及<literal>DROP TABLE</literal>操作都是事务性的，因此一旦该事务提交，该表将以正确的快照开始或者停止复制。
+   表可以使用<link linkend="sql-alterpublication"><command>ALTER PUBLICATION</command></link>动态地增加或者移除。<literal>ADD TABLE</literal>以及<literal>DROP TABLE</literal>操作都是事务性的，因此一旦该事务提交，该表将以正确的快照开始或者停止复制。
   </para>
  </sect1>
 
@@ -321,7 +321,7 @@ ____________________________________________________________________________-->
   </para>
 ____________________________________________________________________________-->
   <para>
-   每一个订阅都将通过一个复制槽（见<xref linkend="streaming-replication-slots"/>）接收更改。预先存在的表数据的初始数据同步过程可能会要求额外的临时复制槽。
+   每一个订阅都将通过一个复制槽（见<xref linkend="streaming-replication-slots"/>）接收更改。预先存在的表数据的初始数据同步过程可能会要求额外的复制槽，并且在数据同步结束后删除。
   </para>
 
 <!--==========================orignal english content==========================
@@ -358,7 +358,7 @@ ____________________________________________________________________________-->
   </para>
 ____________________________________________________________________________-->
   <para>
-   可以使用<xref linkend="sql-createsubscription"/>增加订阅，并且使用<xref linkend="sql-altersubscription"/>在任何时刻停止/继续订阅，还可以使用<xref linkend="sql-dropsubscription"/>删除订阅。
+   可以使用<link linkend="sql-createsubscription"><command>CREATE SUBSCRIPTION</command></link>增加订阅，并且使用<link linkend="sql-altersubscription"><command>ALTER SUBSCRIPTION</command></link>在任何时刻停止/继续订阅，还可以使用<link linkend="sql-dropsubscription"><command>DROP SUBSCRIPTION</command></link>删除订阅。
   </para>
 
 <!--==========================orignal english content==========================
@@ -479,7 +479,15 @@ ____________________________________________________________________________-->
    </para>
 ____________________________________________________________________________-->
    <para>
-    如早前所提到的，每一个（活跃的）订阅会从远（发布）端上的一个复制槽接收更改。通常，远程复制槽是在使用<command>CREATE SUBSCRIPTION</command>创建订阅是自动创建的，并且在使用<command>DROP SUBSCRIPTION</command>删除订阅时，复制槽也会自动被删除。不过，在一些情况下，有必要单独操纵订阅以及其底层的复制槽。下面是一些场景：
+    如早前所提到的，每一个（活跃的）订阅会从远（发布）端上的一个复制槽接收更改。
+    </para>
+   <para>
+    额外的表同步槽通常是临时的，在内部创建以执行初始表同步，并在它们不再被需要时自动删除。这些表同步槽命名为: <quote><literal>pg_%u_sync_%u_%llu</literal></quote>
+    (参数是: Subscription <parameter>oid</parameter>,
+    Table <parameter>relid</parameter>, system identifier <parameter>sysid</parameter>)
+   </para>
+   <para>
+   通常，远程复制槽是在使用<command>CREATE SUBSCRIPTION</command>创建订阅是自动创建的，并且在使用<command>DROP SUBSCRIPTION</command>删除订阅时，复制槽也会自动被删除。不过，在一些情况下，有必要单独操纵订阅以及其底层的复制槽。下面是一些场景：
 
     <itemizedlist>
      <listitem>
@@ -502,7 +510,7 @@ ____________________________________________________________________________-->
 
      <listitem>
       <para>
-       在删除一个订阅是，远程主机不可达。在这种情况下，可以在尝试删除该订阅之前，使用<command>ALTER SUBSCRIPTION</command>将复制槽解除关联。如果远程数据库实例不再存在，那么不需要进一步的行动。不过，如果远程数据库实例只是不可达，那么复制槽应该被手动删除。否则它将会继续保留WAL并且最终可能会导致磁盘被填满。这种情况应该要仔细地研究。
+       在删除一个订阅时，远程主机不可达。在这种情况下，可以在尝试删除该订阅之前，使用<command>ALTER SUBSCRIPTION</command>将复制槽解除关联。如果远程数据库实例不再存在，那么不需要进一步的行动。不过，如果远程数据库实例只是不可达，那么复制槽应该被手动删除（以及任何剩余的表同步槽）。否则它将会继续保留WAL并且最终可能会导致磁盘被填满。这种情况应该要仔细地研究。
       </para>
      </listitem>
     </itemizedlist>
@@ -681,7 +689,7 @@ ____________________________________________________________________________-->
     <para>
      在分区表之间进行复制时，实际的复制来源，缺省情况下，源自发布者上的叶子分区，因此发布者上的分区也必须作为有效的目标表存在于订阅者上。
      (它们可以是叶分区本身，也可以是进一步子分区段，甚至可以是独立的表。)
-     发布还可以指定使用已分区根表的标识和模式来复制更改，而不是使用实际产生更改的各个叶分区的标识和模式(参见<xref linkend="sql-createpublication"/>)。
+     发布还可以指定使用已分区根表的标识和模式来复制更改，而不是使用实际产生更改的各个叶分区的标识和模式(参见<link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>)。
     </para>
    </listitem>
   </itemizedlist>
@@ -771,7 +779,7 @@ ____________________________________________________________________________-->
     </para>
 ____________________________________________________________________________-->
     <para>
-      已有的被订阅表中的初始数据会被快照并且以一种特殊类型的应用进程的并行实例进行拷贝。这种进程将创建自己的临时复制槽并且拷贝现有的数据。一旦现有的数据被拷贝完，工作者会进入到同步模式，主应用进程会流式传递在使用标准逻辑复制拷贝初始数据期间发生的任意改变，这会确保表被带到一种已同步的状态。一旦同步完成，该表的复制的控制权会被交回给主应用进程，其中复制会照常继续。
+      获取现有订阅表中初始数据的快照并且以一种特殊类型的应用进程的并行实例进行拷贝。这种进程将创建自己的复制槽并且拷贝现有的数据。复制完成后，表内容对其他后端可见。一旦现有的数据被拷贝完，worker进程会进入到同步模式，主应用进程会流式更新在使用标准逻辑复制拷贝初始数据期间发生的任意改变，这会确保表变为已同步的状态。在此同步阶段，应用和提交更改的顺序与它们在发布者发生的顺序相同。一旦同步完成，该表的复制的控制权会被交回给主应用进程，其中复制会照常继续。
     </para>
   </sect2>
  </sect1>
@@ -975,7 +983,7 @@ ____________________________________________________________________________-->
   </para>
 ____________________________________________________________________________-->
   <para>
-   订阅者还要求<varname>max_replication_slots</varname>被设置。在这种情况下，它必须至少被设置为将被加入到该订阅者的订阅数。<varname>max_logical_replication_workers</varname>必须至少被设置为订阅数加上保留给表同步的连接数。此外，可能需要调整<varname>max_worker_processes</varname>以容纳复制工作者，至少为(<varname>max_logical_replication_workers</varname> + <literal>1</literal>)。注意，一些扩展和并行查询也会从<varname>max_worker_processes</varname>中取得工作者槽。
+   订阅者必须配置<varname>max_replication_slots</varname>。它必须设置为至少是订阅者数，加上一些用于表同步的预留。<varname>max_logical_replication_workers</varname>必须至少被设置为订阅数加上保留给表同步的连接数。此外，可能需要调整<varname>max_worker_processes</varname>以容纳复制工作者，至少为(<varname>max_logical_replication_workers</varname> + <literal>1</literal>)。注意，一些扩展和并行查询也会从<varname>max_worker_processes</varname>中取得工作者槽。
   </para>
  </sect1>