Skip to content

Commit bcb5307

Browse files
knizhnikknizhnik
committed
2 parents 32156d6 + be1700b commit bcb5307

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+1671
-572
lines changed

‎contrib/test_decoding/expected/binary.out

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'for
1414

1515
-- fails, binary plugin, textual consumer
1616
SELECT data FROM pg_logical_slot_get_changes('regression_slot', NULL, NULL, 'force-binary', '1', 'skip-empty-xacts', '1');
17-
ERROR: logical decoding output plugin "test_decoding" produces binary output, but "pg_logical_slot_get_changes(name,pg_lsn,integer,text[])" expects textual data
17+
ERROR: logical decoding output plugin "test_decoding" produces binary output, but function "pg_logical_slot_get_changes(name,pg_lsn,integer,text[])" expects textual data
1818
-- succeeds, textual plugin, binary consumer
1919
SELECT data FROM pg_logical_slot_get_binary_changes('regression_slot', NULL, NULL, 'force-binary', '0', 'skip-empty-xacts', '1');
2020
data

‎doc/src/sgml/brin.sgml

Lines changed: 191 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -535,7 +535,7 @@ typedef struct BrinOpcInfo
535535
defined by the user for other data types using equivalent definitions,
536536
without having to write any source code; appropriate catalog entries being
537537
declared is enough. Note that assumptions about the semantics of operator
538-
strategies are embedded in the support procedures's source code.
538+
strategies are embedded in the support procedures' source code.
539539
</para>
540540

541541
<para>
@@ -566,19 +566,19 @@ typedef struct BrinOpcInfo
566566
<tbody>
567567
<row>
568568
<entry>Support Procedure 1</entry>
569-
<entry>function <function>brin_minmax_opcinfo()</function></entry>
569+
<entry>internal function <function>brin_minmax_opcinfo()</function></entry>
570570
</row>
571571
<row>
572572
<entry>Support Procedure 2</entry>
573-
<entry>function <function>brin_minmax_add_value()</function></entry>
573+
<entry>internal function <function>brin_minmax_add_value()</function></entry>
574574
</row>
575575
<row>
576576
<entry>Support Procedure 3</entry>
577-
<entry>function <function>brin_minmax_consistent()</function></entry>
577+
<entry>internal function <function>brin_minmax_consistent()</function></entry>
578578
</row>
579579
<row>
580580
<entry>Support Procedure 4</entry>
581-
<entry>function <function>brin_minmax_union()</function></entry>
581+
<entry>internal function <function>brin_minmax_union()</function></entry>
582582
</row>
583583
<row>
584584
<entry>Operator Strategy 1</entry>
@@ -603,5 +603,191 @@ typedef struct BrinOpcInfo
603603
</tbody>
604604
</tgroup>
605605
</table>
606+
607+
<para>
608+
To write an operator class for a complex datatype which has values
609+
included within another type, it's possible to use the inclusion support
610+
procedures alongside the corresponding operators, as shown
611+
in <xref linkend="brin-extensibility-inclusion-table">. It requires
612+
only a single additional function, which can be written in any language.
613+
More functions can be defined for additional functionality. All operators
614+
are optional. Some operators require other operators, as shown as
615+
dependencies on the table.
616+
</para>
617+
618+
<table id="brin-extensibility-inclusion-table">
619+
<title>Procedure and Support Numbers for Inclusion Operator Classes</title>
620+
<tgroup cols="3">
621+
<thead>
622+
<row>
623+
<entry>Operator class member</entry>
624+
<entry>Object</entry>
625+
<entry>Dependency</entry>
626+
</row>
627+
</thead>
628+
<tbody>
629+
<row>
630+
<entry>Support Procedure 1</entry>
631+
<entry>internal function <function>brin_inclusion_opcinfo()</function></entry>
632+
<entry></entry>
633+
</row>
634+
<row>
635+
<entry>Support Procedure 2</entry>
636+
<entry>internal function <function>brin_inclusion_add_value()</function></entry>
637+
<entry></entry>
638+
</row>
639+
<row>
640+
<entry>Support Procedure 3</entry>
641+
<entry>internal function <function>brin_inclusion_consistent()</function></entry>
642+
<entry></entry>
643+
</row>
644+
<row>
645+
<entry>Support Procedure 4</entry>
646+
<entry>internal function <function>brin_inclusion_union()</function></entry>
647+
<entry></entry>
648+
</row>
649+
<row>
650+
<entry>Support Procedure 11</entry>
651+
<entry>function to merge two elements</entry>
652+
<entry></entry>
653+
</row>
654+
<row>
655+
<entry>Support Procedure 12</entry>
656+
<entry>optional function to check whether two elements are mergeable</entry>
657+
<entry></entry>
658+
</row>
659+
<row>
660+
<entry>Support Procedure 13</entry>
661+
<entry>optional function to check if an element is contained within another</entry>
662+
<entry></entry>
663+
</row>
664+
<row>
665+
<entry>Support Procedure 14</entry>
666+
<entry>optional function to check whether an element is empty</entry>
667+
<entry></entry>
668+
</row>
669+
<row>
670+
<entry>Operator Strategy 1</entry>
671+
<entry>operator left-of</entry>
672+
<entry>Operator Strategy 4</entry>
673+
</row>
674+
<row>
675+
<entry>Operator Strategy 2</entry>
676+
<entry>operator does-not-extend-to-the-right-of</entry>
677+
<entry>Operator Strategy 5</entry>
678+
</row>
679+
<row>
680+
<entry>Operator Strategy 3</entry>
681+
<entry>operator overlaps</entry>
682+
<entry></entry>
683+
</row>
684+
<row>
685+
<entry>Operator Strategy 4</entry>
686+
<entry>operator right-of</entry>
687+
<entry>Operator Strategy 2</entry>
688+
</row>
689+
<row>
690+
<entry>Operator Strategy 5</entry>
691+
<entry>operator does-not-extend-to-the-right-of</entry>
692+
<entry>Operator Strategy 1</entry>
693+
</row>
694+
<row>
695+
<entry>Operator Strategy 6, 18</entry>
696+
<entry>operator same-as-or-equal-to</entry>
697+
<entry>Operator Strategy 7</entry>
698+
</row>
699+
<row>
700+
<entry>Operator Strategy 7, 13, 16, 24, 25</entry>
701+
<entry>operator contains-or-equal-to</entry>
702+
<entry></entry>
703+
</row>
704+
<row>
705+
<entry>Operator Strategy 8, 14, 26, 27</entry>
706+
<entry>operator is-contained-by-or-equal-to</entry>
707+
<entry>Operator Strategy 3</entry>
708+
</row>
709+
<row>
710+
<entry>Operator Strategy 9</entry>
711+
<entry>operator does-not-extend-above</entry>
712+
<entry>Operator Strategy 11</entry>
713+
</row>
714+
<row>
715+
<entry>Operator Strategy 10</entry>
716+
<entry>operator is-below</entry>
717+
<entry>Operator Strategy 12</entry>
718+
</row>
719+
<row>
720+
<entry>Operator Strategy 11</entry>
721+
<entry>operator is-above</entry>
722+
<entry>Operator Strategy 9</entry>
723+
</row>
724+
<row>
725+
<entry>Operator Strategy 12</entry>
726+
<entry>operator does-not-extend-below</entry>
727+
<entry>Operator Strategy 10</entry>
728+
</row>
729+
<row>
730+
<entry>Operator Strategy 20</entry>
731+
<entry>operator less-than</entry>
732+
<entry>Operator Strategy 4</entry>
733+
</row>
734+
<row>
735+
<entry>Operator Strategy 21</entry>
736+
<entry>operator less-than-or-equal-to</entry>
737+
<entry>Operator Strategy 4</entry>
738+
</row>
739+
<row>
740+
<entry>Operator Strategy 22</entry>
741+
<entry>operator greater-than</entry>
742+
<entry>Operator Strategy 1</entry>
743+
</row>
744+
<row>
745+
<entry>Operator Strategy 23</entry>
746+
<entry>operator greater-than-or-equal-to</entry>
747+
<entry>Operator Strategy 1</entry>
748+
</row>
749+
</tbody>
750+
</tgroup>
751+
</table>
752+
753+
<para>
754+
Support procedure numbers 1-10 are reserved for the BRIN internal
755+
functions, so the SQL level functions start with number 11. Support
756+
function number 11 is the main function required to build the index.
757+
It should accept two arguments with the same datatype as the opclass,
758+
and return the union of them. The inclusion opclass can store union
759+
values with different datatypes if it is defined with the
760+
<literal>STORAGE</> parameter. The return value of the union
761+
function should match the <literal>STORAGE</> datatype.
762+
</para>
763+
764+
<para>
765+
Support procedure numbers 12 and 14 are provided to support
766+
irregularities of built-in datatypes. Procedure number 12
767+
is used to support network addresses from different families which
768+
are not mergeable. Procedure number 14 is used to support
769+
empty ranges. Procedure number 13 is an optional but
770+
recommended one, which allows the new value to be checked before
771+
it is passed to the union function. As the BRIN framework can shortcut
772+
some operations when the union is not changed, using this
773+
function can improve index performance.
774+
</para>
775+
776+
<para>
777+
Both minmax and inclusion opclasses support cross-datatype
778+
operators, though with these the dependencies become more complicated.
779+
The minmax opclass requires a full set of operators to be
780+
defined with both arguments having the same datatype. It allows
781+
additional datatypes to be supported by defining extra sets
782+
of operators. Inclusion opclass operator strategies are dependent
783+
on another operator strategy as shown in
784+
<xref linkend="brin-extensibility-inclusion-table">, or the same
785+
operator strategy as themselves. They require the dependency
786+
operator to be defined with the <literal>STORAGE</> datatype as the
787+
left-hand-side argument and the other supported datatype to be the
788+
right-hand-side argument of the supported operator. See
789+
<literal>float4_minmax_ops</> as an example of minmax, and
790+
<literal>box_inclusion_ops</> as an example of inclusion.
791+
</para>
606792
</sect1>
607793
</chapter>

‎doc/src/sgml/func.sgml

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4477,13 +4477,27 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
44774477
where no substring matching <replaceable>re</> begins
44784478
(AREs only) </entry>
44794479
</row>
4480+
4481+
<row>
4482+
<entry> <literal>(?&lt;=</><replaceable>re</><literal>)</> </entry>
4483+
<entry> <firstterm>positive lookbehind</> matches at any point
4484+
where a substring matching <replaceable>re</> ends
4485+
(AREs only) </entry>
4486+
</row>
4487+
4488+
<row>
4489+
<entry> <literal>(?&lt;!</><replaceable>re</><literal>)</> </entry>
4490+
<entry> <firstterm>negative lookbehind</> matches at any point
4491+
where no substring matching <replaceable>re</> ends
4492+
(AREs only) </entry>
4493+
</row>
44804494
</tbody>
44814495
</tgroup>
44824496
</table>
44834497

44844498
<para>
4485-
Lookahead constraints cannot contain <firstterm>back references</>
4486-
(see <xref linkend="posix-escape-sequences">),
4499+
Lookahead and lookbehind constraints cannot contain <firstterm>back
4500+
references</> (see <xref linkend="posix-escape-sequences">),
44874501
and all parentheses within them are considered non-capturing.
44884502
</para>
44894503
</sect3>
@@ -5355,7 +5369,7 @@ SELECT regexp_matches('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
53555369
the lack of special treatment for a trailing newline,
53565370
the addition of complemented bracket expressions to the things
53575371
affected by newline-sensitive matching,
5358-
the restrictions on parentheses and back references in lookahead
5372+
the restrictions on parentheses and back references in lookahead/lookbehind
53595373
constraints, and the longest/shortest-match (rather than first-match)
53605374
matching semantics.
53615375
</para>

‎doc/src/sgml/json.sgml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -349,6 +349,34 @@ SELECT '"foo"'::jsonb ? 'foo';
349349
need to be searched linearly.
350350
</para>
351351

352+
<tip>
353+
<para>
354+
Because JSON containment is nested, an appropriate query can skip
355+
explicit selection of sub-objects. As an example, suppose that we have
356+
a <structfield>doc</> column containing objects at the top level, with
357+
most objects containing <literal>tags</> fields that contain arrays of
358+
sub-objects. This query finds entries in which sub-objects containing
359+
both <literal>"term":"paris"</> and <literal>"term":"food"</> appear,
360+
while ignoring any such keys outside the <literal>tags</> array:
361+
<programlisting>
362+
SELECT doc-&gt;'site_name' FROM websites
363+
WHERE doc @&gt; '{"tags":[{"term":"paris"}, {"term":"food"}]}';
364+
</programlisting>
365+
One could accomplish the same thing with, say,
366+
<programlisting>
367+
SELECT doc-&gt;'site_name' FROM websites
368+
WHERE doc-&gt;'tags' @&gt; '[{"term":"paris"}, {"term":"food"}]';
369+
</programlisting>
370+
but that approach is less flexible, and often less efficient as well.
371+
</para>
372+
373+
<para>
374+
On the other hand, the JSON existence operator is not nested: it will
375+
only look for the specified key or array element at top level of the
376+
JSON value.
377+
</para>
378+
</tip>
379+
352380
<para>
353381
The various containment and existence operators, along with all other
354382
JSON operators and functions are documented

0 commit comments

Comments
 (0)