-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathbtree-support-funcs.html
More file actions
259 lines (258 loc) · 25.5 KB
/
btree-support-funcs.html
File metadata and controls
259 lines (258 loc) · 25.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>63.3. B-Treeサポート関数</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="btree-behavior.html" title="63.2. B-Tree演算子クラスの振る舞い" /><link rel="next" href="btree-implementation.html" title="63.4. 実装" /><meta name="viewport" content="width=device-width,initial-scale=1.0" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="4" align="center"><a accesskey="h" href="index.html">PostgreSQL 11.5文書</a></th></tr><tr><td width="10%" align="left"></td><td width="10%" align="left"></td><td width="60%" align="center"><a href="btree.html" title="第63章 B-Treeインデックス">第63章 B-Treeインデックス</a></td><td width="20%" align="right"><div class="actions"><a class="issue" title="github" href="https://github.com/pgsql-jp/jpug-doc/issues/new?title=version 11.5 btree-support-funcs.html">誤訳等の報告
</a></div></td></tr><tr><td width="10%" align="left"><a accesskey="p" href="btree-behavior.html" title="63.2. B-Tree演算子クラスの振る舞い">前へ</a> </td><td width="10%" align="left"><a accesskey="u" href="btree.html" title="第63章 B-Treeインデックス">上へ</a></td><td width="60%" align="center">63.3. B-Treeサポート関数</td><td width="20%" align="right"> <a accesskey="n" href="btree-implementation.html" title="63.4. 実装">次へ</a></td></tr></table><hr /></div><div class="sect1" id="BTREE-SUPPORT-FUNCS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">63.3. B-Treeサポート関数</h2></div></div></div><span class="original">
<title>B-Tree Support Functions</title>
</span><p>
<span class="original">
As shown in <xref linkend="xindex-btree-support-table"/>, btree defines
one required and two optional support functions.
</span>
<a class="xref" href="xindex.html#XINDEX-BTREE-SUPPORT-TABLE" title="表38.8 B-treeサポート関数">表 38.8</a>で示すように、btreeでは一つの必須サポート関数と、２つの省略可能なサポート関数を定義します。
</p><p>
<span class="original">
For each combination of data types that a btree operator family provides
comparison operators for, it must provide a comparison support function,
registered in <structname>pg_amproc</structname> with support function
number 1 and
<structfield>amproclefttype</structfield>/<structfield>amprocrighttype</structfield>
equal to the left and right data types for the comparison (i.e., the
same data types that the matching operators are registered with
in <structname>pg_amop</structname>).
The comparison function must take two non-null values
<replaceable>A</replaceable> and <replaceable>B</replaceable> and
return an <type>int32</type> value that
is <literal>&lt;</literal> <literal>0</literal>, <literal>0</literal>,
or <literal>&gt;</literal> <literal>0</literal>
when <replaceable>A</replaceable> <literal>&lt;</literal>
<replaceable>B</replaceable>, <replaceable>A</replaceable>
<literal>=</literal> <replaceable>B</replaceable>,
or <replaceable>A</replaceable> <literal>&gt;</literal>
<replaceable>B</replaceable>, respectively.
A null result is disallowed: all values of the data type must be comparable.
See <filename>src/backend/access/nbtree/nbtcompare.c</filename> for
examples.
</span>
btree演算子族が比較演算子を提供するそれぞれのデータ型の組において、<code class="structname">pg_amproc</code>でサポート関数番号1と、<code class="structfield">amproclefttype</code>/<code class="structfield">amprocrighttype</code>と等しい比較用の左と右のデータ型（つまり<code class="structname">pg_amop</code>中に定義されている演算子に該当する同じデータ型）が必要です。
比較関数は、２つの非NULL値<em class="replaceable"><code>A</code></em>と<em class="replaceable"><code>B</code></em>を取り、それぞれ<em class="replaceable"><code>A</code></em> <code class="literal"><</code><em class="replaceable"><code>B</code></em>、<em class="replaceable"><code>A</code></em><code class="literal">=</code><em class="replaceable"><code>B</code></em>、あるいは<em class="replaceable"><code>A</code></em><code class="literal">></code><em class="replaceable"><code>B</code></em>であるときに、<code class="literal"><</code><code class="literal">0</code>、<code class="literal">0</code>あるいは<code class="literal">></code><code class="literal">0</code>である<code class="type">int32</code>値を返さなければなりません。
NULLの結果は許されません。
そのデータ型のすべての値が比較可能でなければなりません。
<code class="filename">src/backend/access/nbtree/nbtcompare.c</code>に例があります。
</p><p>
<span class="original">
If the compared values are of a collatable data type, the appropriate
collation OID will be passed to the comparison support function, using
the standard <function>PG_GET_COLLATION()</function> mechanism.
</span>
比較される値の型が照合可能データ型なら、標準の<code class="function">PG_GET_COLLATION()</code>機構を使って、適切な照合OIDが比較サポート関数に渡されます。
</p><p>
<span class="original">
Optionally, a btree operator family may provide <firstterm>sort
support</firstterm> function(s), registered under support function number
2. These functions allow implementing comparisons for sorting purposes
in a more efficient way than naively calling the comparison support
function. The APIs involved in this are defined in
<filename>src/include/utils/sortsupport.h</filename>.
</span>
btree演算子族はオプションで、サポート関数番号2の<em class="firstterm">sort support</em>関数を提供することができます。
これらの関数により、ネィティブの比較サポート関数を呼び出すよりも効率の良いソートを目的とする比較を実装することができます。
このためのAPIは、<code class="filename">src/include/utils/sortsupport.h</code>で定義されています。
</p><a id="id-1.10.15.5.6" class="indexterm"></a><a id="id-1.10.15.5.7" class="indexterm"></a><p>
<span class="original">
Optionally, a btree operator family may
provide <firstterm>in_range</firstterm> support function(s), registered
under support function number 3. These are not used during btree index
operations; rather, they extend the semantics of the operator family so
that it can support window clauses containing
the <literal>RANGE</literal> <replaceable>offset</replaceable>
<literal>PRECEDING</literal>
and <literal>RANGE</literal> <replaceable>offset</replaceable>
<literal>FOLLOWING</literal> frame bound types (see
<xref linkend="syntax-window-functions"/>). Fundamentally, the extra
information provided is how to add or subtract
an <replaceable>offset</replaceable> value in a way that is compatible
with the family's data ordering.
</span>
オプションで、btree演算子族は、サポート関数番号3で登録される<em class="firstterm">in_range</em>サポート関数を提供することができます。
これらはbtreeインデックス操作中には使われませんが、演算子族の意味を拡張し、<code class="literal">RANGE</code> <em class="replaceable"><code>offset</code></em> <code class="literal">PRECEDING</code>と<code class="literal">RANGE</code> <em class="replaceable"><code>offset</code></em> <code class="literal">FOLLOWING</code>フレーム境界型などのwindow句をサポートします（<a class="xref" href="sql-expressions.html#SYNTAX-WINDOW-FUNCTIONS" title="4.2.8. ウィンドウ関数呼び出し">4.2.8</a>参照）。
基本的に余分に追加された情報は、演算子族のデータ順に適合するやりで、<em class="replaceable"><code>offset</code></em>値を加算あるいは減算する方法です。
</p><p>
<span class="original">
An <function>in_range</function> function must have the signature
<synopsis>
in_range(<replaceable>val</replaceable> type1, <replaceable>base</replaceable> type1, <replaceable>offset</replaceable> type2, <replaceable>sub</replaceable> bool, <replaceable>less</replaceable> bool)
returns bool
</synopsis>
<replaceable>val</replaceable> and <replaceable>base</replaceable> must be
of the same type, which is one of the types supported by the operator
family (i.e., a type for which it provides an ordering).
However, <replaceable>offset</replaceable> could be of a different type,
which might be one otherwise unsupported by the family. An example is
that the built-in <literal>time_ops</literal> family provides
an <function>in_range</function> function that
has <replaceable>offset</replaceable> of type <type>interval</type>.
A family can provide <function>in_range</function> functions for any of
its supported types and one or more <replaceable>offset</replaceable>
types. Each <function>in_range</function> function should be entered
in <structname>pg_amproc</structname>
with <structfield>amproclefttype</structfield> equal to <type>type1</type>
and <structfield>amprocrighttype</structfield> equal to <type>type2</type>.
</span>
<code class="function">in_range</code>関数は次のシグネチャーを持たなければなりません。
</p><pre class="synopsis">
in_range(<em class="replaceable"><code>val</code></em> type1, <em class="replaceable"><code>base</code></em> type1, <em class="replaceable"><code>offset</code></em> type2, <em class="replaceable"><code>sub</code></em> bool, <em class="replaceable"><code>less</code></em> bool)
returns bool
</pre><p>
<em class="replaceable"><code>val</code></em>と<em class="replaceable"><code>base</code></em>は演算子族がサポートする同じ型（つまり、順序を提供する型）でなければなりません。
しかし、<em class="replaceable"><code>offset</code></em>は演算子族がサポートしない異なる型でも構いません。
一例として、組み込みの<code class="literal">time_ops</code>族は<code class="type">interval</code>型の<em class="replaceable"><code>offset</code></em>を持つ<code class="function">in_range</code>関数を提供します。
演算子族は、サポートするすべての型のための<code class="function">in_range</code>関数と、複数の<em class="replaceable"><code>offset</code></em>型を提供できます。
個々の<code class="function">in_range</code>関数は、<code class="type">type1</code>と等しい<code class="structfield">amproclefttype</code>と、<code class="type">type2</code>と等しい<code class="structfield">amprocrighttype</code>とともに<code class="structname">pg_amproc</code>に登録すべきです。
</p><p>
<span class="original">
The essential semantics of an <function>in_range</function> function
depend on the two boolean flag parameters. It should add or
subtract <replaceable>base</replaceable>
and <replaceable>offset</replaceable>, then
compare <replaceable>val</replaceable> to the result, as follows:
</span>
<code class="function">in_range</code>関数の本質的な意味は、２つの論理値型フラグ引数に依存しています。
それは<em class="replaceable"><code>base</code></em>に<em class="replaceable"><code>offset</code></em>を加算あるいは減算し、次のように結果を<em class="replaceable"><code>val</code></em>と比較します。
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="original">
if <literal>!</literal><replaceable>sub</replaceable> and
<literal>!</literal><replaceable>less</replaceable>,
return <replaceable>val</replaceable> <literal>&gt;=</literal>
(<replaceable>base</replaceable> <literal>+</literal>
<replaceable>offset</replaceable>)
</span>
<code class="literal">!</code><em class="replaceable"><code>sub</code></em>かつ<code class="literal">!</code><em class="replaceable"><code>less</code></em>なら、<em class="replaceable"><code>val</code></em> <code class="literal">>=</code>(<em class="replaceable"><code>base</code></em> <code class="literal">+</code><em class="replaceable"><code>offset</code></em>)を返します。
</p></li><li class="listitem"><p>
<span class="original">
if <literal>!</literal><replaceable>sub</replaceable>
and <replaceable>less</replaceable>,
return <replaceable>val</replaceable> <literal>&lt;=</literal>
(<replaceable>base</replaceable> <literal>+</literal>
<replaceable>offset</replaceable>)
</span>
<code class="literal">!</code><em class="replaceable"><code>sub</code></em>かつ<em class="replaceable"><code>less</code></em>なら、<em class="replaceable"><code>val</code></em> <code class="literal"><=</code>(<em class="replaceable"><code>base</code></em> <code class="literal">+</code> <em class="replaceable"><code>offset</code></em>)を返します。
</p></li><li class="listitem"><p>
<span class="original">
if <replaceable>sub</replaceable>
and <literal>!</literal><replaceable>less</replaceable>,
return <replaceable>val</replaceable> <literal>&gt;=</literal>
(<replaceable>base</replaceable> <literal>-</literal>
<replaceable>offset</replaceable>)
</span>
<em class="replaceable"><code>sub</code></em>かつ<code class="literal">!</code><em class="replaceable"><code>less</code></em>なら、<em class="replaceable"><code>val</code></em> <code class="literal">>=</code>(<em class="replaceable"><code>base</code></em> <code class="literal">-</code> <em class="replaceable"><code>offset</code></em>)を返します。
</p></li><li class="listitem"><p>
<span class="original">
if <replaceable>sub</replaceable> and <replaceable>less</replaceable>,
return <replaceable>val</replaceable> <literal>&lt;=</literal>
(<replaceable>base</replaceable> <literal>-</literal>
<replaceable>offset</replaceable>)
</span>
<em class="replaceable"><code>sub</code></em>かつ<em class="replaceable"><code>less</code></em>なら、<em class="replaceable"><code>val</code></em> <code class="literal"><=</code>(<em class="replaceable"><code>base</code></em> <code class="literal">-</code> <em class="replaceable"><code>offset</code></em>)を返します。
</p></li></ul></div><p>
<span class="original">
Before doing so, the function should check the sign
of <replaceable>offset</replaceable>: if it is less than zero, raise
error <literal>ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE</literal> (22013)
with error text like <quote>invalid preceding or following size in window
function</quote>. (This is required by the SQL standard, although
nonstandard operator families might perhaps choose to ignore this
restriction, since there seems to be little semantic necessity for it.)
This requirement is delegated to the <function>in_range</function>
function so that the core code needn't understand what <quote>less than
zero</quote> means for a particular data type.
</span>
関数は実行する前に<em class="replaceable"><code>offset</code></em>の符号を検査します。
0より小さければ、<code class="literal">ERRCODE_INVALID_PRECEDING_OR_FOLLOWING_SIZE</code> (22013)をエラー文字列<span class="quote">「<span class="quote">invalid preceding or following size in window function</span>」</span>で引き起こします。
（これはSQL標準によって要求されていますが、非標準の演算子族はおそらくこの制限を無視するかも知れません。意味的に必要性が低いからです。）
この要件は、<code class="function">in_range</code>関数に委任され、あるデータ型にとって<span class="quote">「<span class="quote">0より小さい</span>」</span>ということをコアコードが理解せずに済むようになります。
</p><p>
<span class="original">
An additional expectation is that <function>in_range</function> functions
should, if practical, avoid throwing an error
if <replaceable>base</replaceable> <literal>+</literal>
<replaceable>offset</replaceable>
or <replaceable>base</replaceable> <literal>-</literal>
<replaceable>offset</replaceable> would overflow.
The correct comparison result can be determined even if that value would
be out of the data type's range. Note that if the data type includes
concepts such as <quote>infinity</quote> or <quote>NaN</quote>, extra care
may be needed to ensure that <function>in_range</function>'s results agree
with the normal sort order of the operator family.
</span>
他に期待されることとして、<em class="replaceable"><code>base</code></em> <code class="literal">+</code> <em class="replaceable"><code>offset</code></em>あるいは<em class="replaceable"><code>base</code></em> <code class="literal">-</code> <em class="replaceable"><code>offset</code></em>がオーバーフローしたときに、<code class="function">in_range</code>関数が実用上その方がよければエラーを引き起こすことを防ぐということがあります。
値がデータ型の許す範囲を逸脱していても、正しい比較結果を決定することができます。
データ型に<span class="quote">「<span class="quote">infinity</span>」</span>あるいは<span class="quote">「<span class="quote">NaN</span>」</span>の概念が含まれていると、<code class="function">in_range</code>の結果が演算子族の通常のソート順と矛盾しないように追加の考慮が必要になるかも知れません。
</p><p>
<span class="original">
The results of the <function>in_range</function> function must be
consistent with the sort ordering imposed by the operator family.
To be precise, given any fixed values of <replaceable>offset</replaceable>
and <replaceable>sub</replaceable>, then:
</span>
<code class="function">in_range</code>関数の結果は、演算子族が課するソート順と矛盾がないようにしなければなりません。
もっと正確に言うと、<em class="replaceable"><code>offset</code></em>と<em class="replaceable"><code>sub</code></em>のどんな値に対しても次のようになります。
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="original">
If <function>in_range</function> with <replaceable>less</replaceable> =
true is true for some <replaceable>val1</replaceable>
and <replaceable>base</replaceable>, it must be true for
every <replaceable>val2</replaceable> <literal>&lt;=</literal>
<replaceable>val1</replaceable> with the
same <replaceable>base</replaceable>.
</span>
ある<em class="replaceable"><code>val1</code></em>と<em class="replaceable"><code>base</code></em>に対して、<em class="replaceable"><code>less</code></em> = trueである<code class="function">in_range</code>がtrueならば、ある<em class="replaceable"><code>base</code></em>のすべての<em class="replaceable"><code>val2</code></em><code class="literal"><=</code><em class="replaceable"><code>val1</code></em>に対してtrueでなければなりません。
</p></li><li class="listitem"><p>
<span class="original">
If <function>in_range</function> with <replaceable>less</replaceable> =
true is false for some <replaceable>val1</replaceable>
and <replaceable>base</replaceable>, it must be false for
every <replaceable>val2</replaceable> <literal>&gt;=</literal>
<replaceable>val1</replaceable> with the
same <replaceable>base</replaceable>.
</span>
ある<em class="replaceable"><code>val1</code></em>と<em class="replaceable"><code>base</code></em>に対して、<em class="replaceable"><code>less</code></em> = trueである<code class="function">in_range</code>がfalseならば、ある<em class="replaceable"><code>base</code></em>のすべての<em class="replaceable"><code>val2</code></em><code class="literal">>=</code><em class="replaceable"><code>val1</code></em>に対してfalseでなければなりません。
</p></li><li class="listitem"><p>
<span class="original">
If <function>in_range</function> with <replaceable>less</replaceable> =
true is true for some <replaceable>val</replaceable>
and <replaceable>base1</replaceable>, it must be true for
every <replaceable>base2</replaceable> <literal>&gt;=</literal>
<replaceable>base1</replaceable> with the
same <replaceable>val</replaceable>.
</span>
ある<em class="replaceable"><code>val</code></em>と<em class="replaceable"><code>base1</code></em>に対して、<em class="replaceable"><code>less</code></em> = trueである<code class="function">in_range</code>がtrueならば、ある<em class="replaceable"><code>val</code></em>のすべての<em class="replaceable"><code>val2</code></em><code class="literal">>=</code><em class="replaceable"><code>base1</code></em>に対してtrueでなければなりません。
</p></li><li class="listitem"><p>
<span class="original">
If <function>in_range</function> with <replaceable>less</replaceable> =
true is false for some <replaceable>val</replaceable>
and <replaceable>base1</replaceable>, it must be false for
every <replaceable>base2</replaceable> <literal>&lt;=</literal>
<replaceable>base1</replaceable> with the
same <replaceable>val</replaceable>.
</span>
ある<em class="replaceable"><code>val</code></em>と<em class="replaceable"><code>base1</code></em>に対して、<em class="replaceable"><code>less</code></em> = trueである<code class="function">in_range</code>がfalseならば、ある<em class="replaceable"><code>val</code></em>のすべての<em class="replaceable"><code>base2</code></em><code class="literal"><=</code><em class="replaceable"><code>base1</code></em>に対してfalseでなければなりません。
</p></li></ul></div><p>
<span class="original">
Analogous statements with inverted conditions hold
when <replaceable>less</replaceable> = false.
</span>
<em class="replaceable"><code>less</code></em> = falseのときには、逆の条件のもとで類似の表明が成り立ちます。
</p><p>
<span class="original">
If the type being ordered (<type>type1</type>) is collatable,
the appropriate collation OID will be passed to
the <function>in_range</function> function, using the standard
PG_GET_COLLATION() mechanism.
</span>
順序付けされている型(<code class="type">type1</code>)が照合可能ならば、標準の<code class="function">PG_GET_COLLATION()</code>機構を使って、適切な照合OIDが<code class="function">in_range</code>関数に渡されます。
</p><p>
<span class="original">
<function>in_range</function> functions need not handle NULL inputs, and
typically will be marked strict.
</span>
<code class="function">in_range</code>関数はNULL入力を扱う必要がなく、典型的にはstrictとマークされます。
</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="btree-behavior.html">前へ</a> </td><td width="20%" align="center"><a accesskey="u" href="btree.html">上へ</a></td><td width="40%" align="right"> <a accesskey="n" href="btree-implementation.html">次へ</a></td></tr><tr><td width="40%" align="left" valign="top">63.2. B-Tree演算子クラスの振る舞い </td><td width="20%" align="center"><a accesskey="h" href="index.html">ホーム</a></td><td width="40%" align="right" valign="top"> 63.4. 実装</td></tr></table></div></body></html>