33 <sect2 id="jsquery-introduction">
44 <title>Introduction</title>
55 <para>
6- JsQuery - is a language to query jsonb data type, introduced in
6+ JsQuery is a language to query jsonb data type, introduced in
77 PostgreSQL release 9.4.
88 </para>
99 <para>
10- It's primary goal is to provide an additional functionality to
10+ Its primary goal is to provide an additional functionality to
1111 jsonb (currently missing in PostgreSQL), such as a simple and
1212 effective way to search in nested objects and arrays, more
13- comparison operators with indexes support. We hope, that jsquery
13+ comparison operators with indexes support. We hope that jsquery
1414 will be eventually a part of PostgreSQL.
1515 </para>
1616 <para>
@@ -72,7 +72,7 @@ CREATE EXTENSION jsquery;
7272 <para>
7373 Simple expression is specified as
7474 <literal>path binary_operator value</literal> or
75- <literal>path unary_operator</literal>. See following examples.
75+ <literal>path unary_operator</literal>. See the following examples.
7676 </para>
7777 <itemizedlist spacing="compact">
7878 <listitem>
@@ -135,9 +135,9 @@ CREATE EXTENSION jsquery;
135135 </itemizedlist>
136136 <para>
137137 Path selects set of JSON values to be checked using given
138- operators. In the simplest case path is just an key name. In
139- general path is key names and placeholders combined by dot signs.
140- Path can use following placeholders:
138+ operators. In the simplest case, path is just a key name. In
139+ general, path is key names and placeholders combined by dot signs.
140+ Path can use the following placeholders:
141141 </para>
142142 <itemizedlist spacing="compact">
143143 <listitem>
@@ -176,7 +176,7 @@ CREATE EXTENSION jsquery;
176176 <para>
177177 Key names could be given either with or without double quotes. Key
178178 names without double quotes shouldn't contain spaces, start with
179- number or concur with jsquery keyword.
179+ number, or concur with jsquery keyword.
180180 </para>
181181 <para>
182182 The supported binary operators are:
@@ -256,25 +256,26 @@ CREATE EXTENSION jsquery;
256256 <itemizedlist spacing="compact">
257257 <listitem>
258258 <para>
259- <literal>#(a = 1 AND b = 2)</literal> - exists element of
260- array which a key is 1 and b key is 2
259+ <literal>#(a = 1 AND b = 2)</literal> - an array contains
260+ an element where the <literal>a</literal> key is 2
261+ and the <literal>b</literal> key is 2
261262 </para>
262263 </listitem>
263264 <listitem>
264265 <para>
265- <literal>%($ >= 10 AND $ <= 20)</literal> - exists
266- object key which values is between 10 and 20
266+ <literal>%($ >= 10 AND $ <= 20)</literal> - an
267+ object contains a key with a value between 10 and 20
267268 </para>
268269 </listitem>
269270 </itemizedlist>
270271 <para>
271- Path also could contain following special placeholders with
272+ Path also could contain the following special placeholders with
272273 "every" semantics:
273274 </para>
274275 <itemizedlist spacing="compact">
275276 <listitem>
276277 <para>
277- <literal>#:</literal> - every indexes of array;
278+ <literal>#:</literal> - every index of array;
278279 </para>
279280 </listitem>
280281 <listitem>
@@ -290,14 +291,14 @@ CREATE EXTENSION jsquery;
290291 </listitem>
291292 </itemizedlist>
292293 <para>
293- Consider following example.
294+ Consider the following example.
294295 </para>
295296 <programlisting>
296297%.#:($ >= 0 AND $ <= 1)
297298</programlisting>
298299 <para>
299- This example could be read as following : there is at least one key
300- which value is array of numerics between 0 and 1.
300+ This example could be read as follows : there is at least one key
301+ for which the value is an array of numerics between 0 and 1.
301302 </para>
302303 <para>
303304 We can rewrite this example in the following form with extra
@@ -309,7 +310,7 @@ CREATE EXTENSION jsquery;
309310 <para>
310311 The first placeholder <literal>%</literal> checks that expression
311312 in braces is true for at least one value in object. The second
312- placeholder <literal>#:</literal> checks value to be array and all
313+ placeholder <literal>#:</literal> checks that the value is an array and all
313314 its elements satisfy expressions in braces.
314315 </para>
315316 <para>
@@ -321,7 +322,7 @@ CREATE EXTENSION jsquery;
321322</programlisting>
322323 <para>
323324 In this example we transform assertion that every element of array
324- satisfy some condition to assertion that there is no one element
325+ satisfies some condition to assertion that there is no one element
325326 which doesn't satisfy the same condition.
326327 </para>
327328 <para>
@@ -350,7 +351,7 @@ CREATE EXTENSION jsquery;
350351 <listitem>
351352 <para>
352353 <literal>documents.#:.% = *</literal> - "documents"
353- is array of objects containing at least one key.
354+ is an array of objects containing at least one key.
354355 </para>
355356 </listitem>
356357 <listitem>
@@ -362,41 +363,41 @@ CREATE EXTENSION jsquery;
362363 <listitem>
363364 <para>
364365 <literal>#.% = true</literal> - at least one array element is
365- objects which contains at least one "true" value.
366+ an object that contains at least one "true" value.
366367 </para>
367368 </listitem>
368369 </itemizedlist>
369370 <para>
370371 Usage of path operators and braces need some explanation. When
371- same path operators are used multiple times they may refer
372- different values while you can refer same value multiple time by
373- using braces and <literal>$</literal> operator. See following
372+ same path operators are used multiple times they may refer to
373+ different values while you can refer to the same value multiple times by
374+ using braces and <literal>$</literal> operator. See the following
374375 examples.
375376 </para>
376377 <itemizedlist spacing="compact">
377378 <listitem>
378379 <para>
379- <literal># < 10 AND # > 20</literal> - exists element
380- less than 10 and exists another element greater than 20.
380+ <literal># < 10 AND # > 20</literal> - there is an element
381+ less than 10 and another element greater than 20.
381382 </para>
382383 </listitem>
383384 <listitem>
384385 <para>
385- <literal>#($ < 10 AND $ > 20)</literal> - exists element
386- which both less than 10 and greater than 20 (impossible).
386+ <literal>#($ < 10 AND $ > 20)</literal> - there is an element
387+ that is both less than 10 and greater than 20 (impossible).
387388 </para>
388389 </listitem>
389390 <listitem>
390391 <para>
391- <literal>#($ >= 10 AND $ <= 20)</literal> - exists
392+ <literal>#($ >= 10 AND $ <= 20)</literal> - there is an
392393 element between 10 and 20.
393394 </para>
394395 </listitem>
395396 <listitem>
396397 <para>
397- <literal># >= 10 AND # <= 20</literal> - exists element
398- great or equal to 10 and exists another element less or equal
399- to 20. Query can be satisfied by array with no elements
398+ <literal># >= 10 AND # <= 20</literal> - there is an element
399+ great than or equal to 10 and another element less than or equal
400+ to 20. The query can be satisfied by an array with no elements
400401 between 10 and 20, for instance [0,30].
401402 </para>
402403 </listitem>
@@ -409,7 +410,7 @@ CREATE EXTENSION jsquery;
409410 Type checking operators and "every" placeholders are
410411 useful for document schema validation. JsQuery matching operator
411412 <literal>@@</literal> is immutable and can be used in CHECK
412- constraint. See following example.
413+ constraint. See the following example.
413414 </para>
414415 <programlisting>
415416CREATE TABLE js (
@@ -453,14 +454,14 @@ CREATE TABLE js (
453454 </itemizedlist>
454455 <para>
455456 In each of two GIN opclasses jsonb documents are decomposed into
456- entries. Each entry is associated with particular value and it's
457+ entries. Each entry is associated with a particular value and its
457458 path. Difference between opclasses is in the entry representation,
458- comparison and usage for search optimization.
459+ comparison, and usage for search optimization.
459460 </para>
460461 <para>
461462 For example, jsonb document
462463 <literal>{"a": [{"b": "xyz", "c": true}, 10], "d": {"e": [7, false]}}</literal>
463- would be decomposed into following entries:
464+ would be decomposed into the following entries:
464465 </para>
465466 <itemizedlist spacing="compact">
466467 <listitem>
@@ -490,9 +491,9 @@ CREATE TABLE js (
490491 </listitem>
491492 </itemizedlist>
492493 <para>
493- Since JsQuery doesn't support search in particular array index, we
494+ Since JsQuery doesn't support search in a particular array index, we
494495 consider all array elements to be equivalent. Thus, each array
495- element is marked with same <literal>#</literal> sign in the path.
496+ element is marked with the same <literal>#</literal> sign in the path.
496497 </para>
497498 <para>
498499 Major problem in the entries representation is its size. In the
@@ -505,7 +506,7 @@ CREATE TABLE js (
505506 <title>jsonb_path_value_ops</title>
506507 <para>
507508 jsonb_path_value_ops represents entry as pair of path hash and
508- value. Following pseudocode illustrates it.
509+ value. The following pseudocode illustrates it.
509510 </para>
510511 <programlisting>
511512(hash(path_item_1.path_item_2. ... .path_item_n); value)
@@ -534,7 +535,7 @@ CREATE TABLE js (
534535 features of this opclass. Since value is the higher part of
535536 entry we can perform only exact value search efficiently. Range
536537 value search is possible as well but we would have to filter all
537- the the different paths where matching values occur. Bloom
538+ the different paths where matching values occur. Bloom
538539 filter over path items allows index usage for conditions
539540 containing <literal>%</literal> and <literal>*</literal> in
540541 their paths.
@@ -547,7 +548,7 @@ CREATE TABLE js (
547548 valuable for developer or administrator to see the result of
548549 such optimization. Unfortunately, opclasses aren't allowed to do
549550 any custom output to the EXPLAIN. That's why JsQuery provides
550- following functions which allows to see how particular opclass
551+ the following functions which allows to see how particular opclass
551552 optimizes given query.
552553 </para>
553554 <itemizedlist spacing="compact">
@@ -566,7 +567,7 @@ CREATE TABLE js (
566567 </itemizedlist>
567568 <para>
568569 Result of these functions is a textual representation of query
569- tree which leafs are GIN search entries. Following examples show
570+ tree which leaves are GIN search entries. The following examples show
570571 different results of query optimization by different opclasses.
571572 </para>
572573 <programlisting>
@@ -585,11 +586,11 @@ CREATE TABLE js (
585586 y = 2 , entry 2 +
586587</programlisting>
587588 <para>
588- Unfortunately, jsonb have no statistics yet. That's why JsQuery
589+ Unfortunately, jsonb has no statistics yet. That's why JsQuery
589590 optimizer has to do imperative decision while selecting
590591 conditions to be evaluated using index. This decision is made by
591592 assumption that some condition types are less selective than
592- others. Optimizer divides conditions into following selectivity
593+ others. Optimizer divides conditions into the following selectivity
593594 class (listed by descending of selectivity).
594595 </para>
595596 <orderedlist numeration="arabic" spacing="compact">
@@ -638,7 +639,7 @@ CREATE TABLE js (
638639 inaccurate. That's why JsQuery supports hints. Comments
639640 <literal>/*-- index */</literal> and
640641 <literal>/*-- noindex */</literal> placed in the conditions
641- forces optimizer to use and not use index correspondingly.
642+ forces optimizer to use and not to use index correspondingly.
642643 </para>
643644 <programlisting>
644645 SELECT gin_debug_query_path_value('x = 1 AND y /*-- index */ > 0');
@@ -658,14 +659,14 @@ CREATE TABLE js (
658659 <sect2 id="jsquery-contribution">
659660 <title>Contribution</title>
660661 <para>
661- Please, notice, that JsQuery is still under development and while
662- it's stable and tested, it may contains some bugs. Don't hesitate
662+ Please, notice, that JsQuery is still under development and before
663+ it's stable and tested, it may contain some bugs. Don't hesitate
663664 to raise
664665 <ulink url="https://github.com/akorotkov/jsquery/issues">issues at
665666 github</ulink> with your bug reports.
666667 </para>
667668 <para>
668- If you're lacking of some functionality in JsQuery and feeling
669+ If you're lacking some functionality in JsQuery and feeling
669670 power to implement it then you're welcome to make pull requests.
670671 </para>
671672 </sect2>
0 commit comments