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
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
-
- This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
- project.
-
- Copyright (C) 1998-2018 OpenLink Software
-
- This project is free software; you can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation; only version 2 of the License, dated June 1991.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License for more details.
-
- You should have received a copy of the GNU General Public License along
- with this program; if not, write to the Free Software Foundation, Inc.,
- 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-
-
-->
<refentry id="fn_contains">
<refmeta>
<refentrytitle>contains</refentrytitle>
<refmiscinfo>ft</refmiscinfo>
</refmeta>
<refnamediv>
<refname>contains</refname>
<refpurpose>A text contains predicate</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis id="fsyn_contains">
<funcprototype id="fproto_contains">
<funcdef>boolean <function>contains</function></funcdef>
<paramdef><parameter>column</parameter> varchar</paramdef>
<paramdef><parameter>expression</parameter> varchar</paramdef>
<paramdef><optional><parameter>opt_or_value</parameter>integer</optional></paramdef>
<varargs/>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="desc_contains">
<title>Description</title>
<para> This is a SQL predicate that specifies a condition on a column
on which a free text index exists. The expression is a
<type>string</type> matching the grammar of a text search expression.
This is computed for each evaluation of the contains predicate and
does not have to be a constant. For example a parameter or variable
of a containing score (e.g. procedure) is accepted. </para>
<para>The <parameter>score_limit</parameter> is optional. If
specified, it should be a numeric expression determining the minimum score
required to produce a hit.</para>
<para>A virtual column named 'SCORE' is available in queries
involving a <function>contains</function> predicate. This can for
example be returned in a result set or used for sorting.
Note that the name is in upper case and is case sensitive in all
case modes.</para>
</refsect1>
<refsect1 id="params_contains"><title>Parameters</title>
<refsect2><title><parameter>column</parameter></title>
<para>The table column whose contents are free text indexed</para>
</refsect2>
<refsect2><title><parameter>expression</parameter></title>
<para>A <type>string</type> matching the grammar of a text search
expression.</para>
</refsect2>
<refsect2><title><parameter>opt_or_value</parameter></title>
<para>May be one or more of the following:
<variablelist>
<varlistentry>
<term>DESCENDING</term>
<listitem>
<para>specifies that the search will produce the hit with the
greatest id first, as defined by <type>integer</type> or
<type>composite</type> collation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>START_ID ','
<parameter>scalar_exp</parameter></term>
<listitem>
<para>the first allowed document id to be selected by the
expression in its traversal order, e.g. least or equal for
ascending and greatest or equal for descending.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>END_ID ','
<parameter>scalar_exp</parameter></term>
<listitem>
<para>the last allowed id in the traversal order. For
descending order the <parameter>START_ID</parameter> must be >=
<parameter>END_ID</parameter> for hits to
be able to exist. For ascending order the
<parameter>START_ID</parameter> must be <=
<parameter>END_ID</parameter> for hits to be able to
exist.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SCORE_LIMIT ','
<parameter>scalar_exp</parameter></term>
<listitem>
<para>Minimum score that hits must have or exceed to be
considered matches of the predicate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RANGES ','
<parameter>scalar_exp</parameter></term>
<listitem>
<para>specifies that the query variable following the
<parameter>RANGES</parameter> keyword will be bound to the word
position ranges of the hits of the expression inside the
document. The variable is in scope inside the enclosing
<emphasis>SELECT</emphasis> statement.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>OFFBAND ','<parameter>column</parameter></term>
<listitem>
<para>Specifies that the following column will be
retrieved from the free text index instead of the
actual table. For this to be possible the column must have
been declared as offband with the <emphasis>CLUSTERED WITH</emphasis>
option of the <emphasis>CREATE TEXT INDEX</emphasis> statement.</para>
</listitem>
</varlistentry>
</variablelist>
</para></refsect2>
<!-- refsect2><title></title>
<para></para></refsect2>
<refsect2><title></title>
<para></para></refsect2 -->
</refsect1>
<refsect1 id="ret_contains"><title>Return Types</title>
<para>The contains is a predicate, therefore returning a
<type>boolean</type>.</para>
</refsect1>
<!-- refsect1 id="errors_contains"><title>Errors</title>
<table><title>Errors signalled by <function>contains</function></title>
<tgroup cols="4">
<thead>
<row>
<entry>sqlstate</entry><entry>error code</entry><entry>error text</entry><entry>description</entry>
</row>
</thead>
<tbody>
<row>
<entry><errorcode></errorcode></entry>
<entry><errorcode></errorcode></entry>
<entry><errorname></errorname></entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1 -->
<refsect1 id="examples_contains"><title>Examples</title>
<example id="ex_contains"><title>Querying Free Text Indexed Columns using contains()</title>
<itemizedlist>
<listitem>
<para>Return the number of documents with one or more occurrences of "virtual"
immediately followed by "database".</para>
<programlisting>
select count (*) from docs
where contains (text, '"virtual database"')
</programlisting>
</listitem>
<listitem>
<para>Specify documents with performance and either
'tuning' or optimization' in any respective positions.</para>
<programlisting>
'performance and (tuning or optimization)'
</programlisting>
</listitem>
<listitem>
<para>
Match documents with the word graphics more than 100
words away from 'user' or 'interface'.
</para>
<programlisting>
'graphics and not (graphics near user near interface)'
</programlisting>
</listitem>
<listitem>
<para>
Match documents with SQL followed by a word beginning with 'interfac'.
</para>
<programlisting>
'"sql interfac*"'
</programlisting>
</listitem>
<listitem>
<para>
Match documents with words beginning with 'dragon' and not containing the phrase
'once upon a time'.
</para>
<programlisting>
'"dragon*" and not "once upon a time"'
</programlisting>
</listitem>
</itemizedlist>
</example>
<note>
<title>Note:</title>
<para>
An expression may not consist of all negative terms, e.g. (not a) and (not
b) is not a valid expression but 'c and not a and not b' is a valid
expression.
</para>
<para>
Note that the NEAR connective may not be used between AND'ed or
OR'ed terms. It can be used to combine words or phrases.
</para>
</note>
</refsect1>
<refsect1 id="seealso_contains"><title>See Also</title>
<para><link linkend="fn_xpath_contains"><function>xpath_contains()</function></link></para>
<para><link linkend="freetext">The Free Text Index Chapter.</link></para>
<para><link linkend="fttfuncs">Other Free Text Functions.</link></para>
<para><link linkend="txttrig">Free Text Triggers.</link></para>
</refsect1>
</refentry>
|
