blob: 7f0c4e6eb1cce5a87bf9264b5f8a8bbfb96bd62b [file] [log] [blame]
Ian Maxonbf2c56b2017-01-24 14:14:49 -08001<!DOCTYPE html>
2<!--
Ian Maxond5b11d82017-01-25 10:48:05 -08003 | Generated by Apache Maven Doxia at 2017-01-25
Ian Maxonbf2c56b2017-01-24 14:14:49 -08004 | Rendered using Apache Maven Fluido Skin 1.3.0
5-->
6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8 <meta charset="UTF-8" />
9 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
Ian Maxond5b11d82017-01-25 10:48:05 -080010 <meta name="Date-Revision-yyyymmdd" content="20170125" />
Ian Maxonbf2c56b2017-01-24 14:14:49 -080011 <meta http-equiv="Content-Language" content="en" />
12 <title>AsterixDB &#x2013; AsterixDB Support of Full-text search queries</title>
13 <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
14 <link rel="stylesheet" href="../css/site.css" />
15 <link rel="stylesheet" href="../css/print.css" media="print" />
16
17
18 <script type="text/javascript" src="../js/apache-maven-fluido-1.3.0.min.js"></script>
19
20
21
Ian Maxonbf2c56b2017-01-24 14:14:49 -080022
Ian Maxonbf2c56b2017-01-24 14:14:49 -080023
24 </head>
25 <body class="topBarDisabled">
26
27
28
29
30 <div class="container-fluid">
31 <div id="banner">
32 <div class="pull-left">
33 <a href=".././" id="bannerLeft">
34 <img src="../images/asterixlogo.png" alt="AsterixDB"/>
35 </a>
36 </div>
37 <div class="pull-right"> </div>
38 <div class="clear"><hr/></div>
39 </div>
40
41 <div id="breadcrumbs">
42 <ul class="breadcrumb">
43
44
Ian Maxond5b11d82017-01-25 10:48:05 -080045 <li id="publishDate">Last Published: 2017-01-25</li>
Ian Maxonbf2c56b2017-01-24 14:14:49 -080046
47
48
49 <li id="projectVersion" class="pull-right">Version: 0.9.0</li>
50
51 <li class="divider pull-right">|</li>
52
53 <li class="pull-right"> <a href="../index.html" title="Documentation Home">
54 Documentation Home</a>
55 </li>
56
57 </ul>
58 </div>
59
60
61 <div class="row-fluid">
62 <div id="leftColumn" class="span3">
63 <div class="well sidebar-nav">
64
65
66 <ul class="nav nav-list">
67 <li class="nav-header">Get Started - Installation</li>
68
69 <li>
70
71 <a href="../ncservice.html" title="Option 1: using NCService">
72 <i class="none"></i>
73 Option 1: using NCService</a>
74 </li>
75
76 <li>
77
78 <a href="../install.html" title="Option 2: using Managix">
79 <i class="none"></i>
80 Option 2: using Managix</a>
81 </li>
82
83 <li>
84
85 <a href="../yarn.html" title="Option 3: using YARN">
86 <i class="none"></i>
87 Option 3: using YARN</a>
88 </li>
89 <li class="nav-header">AsterixDB Primer</li>
90
91 <li>
92
93 <a href="../sqlpp/primer-sqlpp.html" title="Option 1: using SQL++">
94 <i class="none"></i>
95 Option 1: using SQL++</a>
96 </li>
97
98 <li>
99
100 <a href="../aql/primer.html" title="Option 2: using AQL">
101 <i class="none"></i>
102 Option 2: using AQL</a>
103 </li>
104 <li class="nav-header">Data Model</li>
105
106 <li>
107
108 <a href="../datamodel.html" title="The Asterix Data Model">
109 <i class="none"></i>
110 The Asterix Data Model</a>
111 </li>
112 <li class="nav-header">Queries - SQL++</li>
113
114 <li>
115
116 <a href="../sqlpp/manual.html" title="The SQL++ Query Language">
117 <i class="none"></i>
118 The SQL++ Query Language</a>
119 </li>
120
121 <li>
122
123 <a href="../sqlpp/builtins.html" title="Builtin Functions">
124 <i class="none"></i>
125 Builtin Functions</a>
126 </li>
127 <li class="nav-header">Queries - AQL</li>
128
129 <li>
130
131 <a href="../aql/manual.html" title="The Asterix Query Language (AQL)">
132 <i class="none"></i>
133 The Asterix Query Language (AQL)</a>
134 </li>
135
136 <li>
137
138 <a href="../aql/builtins.html" title="Builtin Functions">
139 <i class="none"></i>
140 Builtin Functions</a>
141 </li>
142 <li class="nav-header">Advanced Features</li>
143
144 <li>
145
146 <a href="../aql/similarity.html" title="Support of Similarity Queries">
147 <i class="none"></i>
148 Support of Similarity Queries</a>
149 </li>
150
151 <li class="active">
152
153 <a href="#"><i class="none"></i>Support of Full-text Queries</a>
154 </li>
155
156 <li>
157
158 <a href="../aql/externaldata.html" title="Accessing External Data">
159 <i class="none"></i>
160 Accessing External Data</a>
161 </li>
162
163 <li>
164
165 <a href="../feeds/tutorial.html" title="Support for Data Ingestion">
166 <i class="none"></i>
167 Support for Data Ingestion</a>
168 </li>
169
170 <li>
171
172 <a href="../udf.html" title="User Defined Functions">
173 <i class="none"></i>
174 User Defined Functions</a>
175 </li>
176
177 <li>
178
179 <a href="../aql/filters.html" title="Filter-Based LSM Index Acceleration">
180 <i class="none"></i>
181 Filter-Based LSM Index Acceleration</a>
182 </li>
183 <li class="nav-header">API/SDK</li>
184
185 <li>
186
187 <a href="../api.html" title="HTTP API">
188 <i class="none"></i>
189 HTTP API</a>
190 </li>
191 </ul>
192
193
194
195 <hr class="divider" />
196
197 <div id="poweredBy">
198 <div class="clear"></div>
199 <div class="clear"></div>
200 <div class="clear"></div>
201 <a href=".././" title="AsterixDB" class="builtBy">
202 <img class="builtBy" alt="AsterixDB" src="../images/asterixlogo.png" />
203 </a>
204 </div>
205 </div>
206 </div>
207
208
209 <div id="bodyColumn" class="span9" >
210
211 <!-- ! Licensed to the Apache Software Foundation (ASF) under one
212 ! or more contributor license agreements. See the NOTICE file
213 ! distributed with this work for additional information
214 ! regarding copyright ownership. The ASF licenses this file
215 ! to you under the Apache License, Version 2.0 (the
216 ! "License"); you may not use this file except in compliance
217 ! with the License. You may obtain a copy of the License at
218 !
219 ! http://www.apache.org/licenses/LICENSE-2.0
220 !
221 ! Unless required by applicable law or agreed to in writing,
222 ! software distributed under the License is distributed on an
223 ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
224 ! KIND, either express or implied. See the License for the
225 ! specific language governing permissions and limitations
226 ! under the License.
227 ! --><h1>AsterixDB Support of Full-text search queries</h1>
228<div class="section">
229<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of Contents</a></h2>
230
231<ul>
232
233<li><a href="#Motivation">Motivation</a></li>
234
235<li><a href="#Syntax">Syntax</a></li>
236
237<li><a href="#FulltextIndex">Creating and utilizing a Full-text index</a></li>
238</ul></div>
239<div class="section">
240<h2><a name="Motivation_Back_to_TOC"></a><a name="Motivation" id="Motivation">Motivation</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2>
241<p>Full-Text Search (FTS) queries are widely used in applications where users need to find records that satisfy an FTS predicate, i.e., where simple string-based matching is not sufficient. These queries are important when finding documents that contain a certain keyword is crucial. FTS queries are different from substring matching queries in that FTS queries find their query predicates as exact keywords in the given string, rather than treating a query predicate as a sequence of characters. For example, an FTS query that finds &#x201c;rain&#x201d; correctly returns a document when it contains &#x201c;rain&#x201d; as a word. However, a substring-matching query returns a document whenever it contains &#x201c;rain&#x201d; as a substring, for instance, a document with &#x201c;brain&#x201d; or &#x201c;training&#x201d; would be returned as well.</p></div>
242<div class="section">
243<h2><a name="Syntax_Back_to_TOC"></a><a name="Syntax" id="Syntax">Syntax</a> <font size="4"><a href="#toc">[Back to TOC]</a></font></h2>
244<p>The syntax of AsterixDB FTS follows a portion of the XQuery FullText Search syntax. Two basic forms are as follows:</p>
245
246<div class="source">
247<div class="source">
248<pre> ftcontains(Expression1, Expression2, {FullTextOption})
249 ftcontains(Expression1, Expression2)
250</pre></div></div>
251<p>For example, we can execute the following query to find tweet messages where the <tt>message-text</tt> field includes &#x201c;voice&#x201d; as a word. Please note that an FTS search is case-insensitive. Thus, &#x201c;Voice&#x201d; or &#x201c;voice&#x201d; will be evaluated as the same word.</p>
252
253<div class="source">
254<div class="source">
255<pre> use dataverse TinySocial;
256
257 for $msg in dataset TweetMessages
258 where ftcontains($msg.message-text, &quot;voice&quot;, {&quot;mode&quot;:&quot;any&quot;})
259 return {&quot;id&quot;: $msg.id}
260</pre></div></div>
261<p>The DDL and DML of TinySocial can be found in <a href="primer.html#ADM:_Modeling_Semistructed_Data_in_AsterixDB">ADM: Modeling Semistructed Data in AsterixDB</a>.</p>
262<p>The <tt>Expression1</tt> is an expression that should be evaluable as a string at runtime as in the above example where <tt>$msg.message-text</tt> is a string field. The <tt>Expression2</tt> can be a string, an (un)ordered list of string value(s), or an expression. In the last case, the given expression should be evaluable into one of the first two types, i.e., into a string value or an (un)ordered list of string value(s).</p>
263<p>The following examples are all valid expressions.</p>
264
265<div class="source">
266<div class="source">
267<pre> ... where ftcontains($msg.message-text, &quot;sound&quot;)
268 ... where ftcontains($msg.message-text, &quot;sound&quot;, {&quot;mode&quot;:&quot;any&quot;})
269 ... where ftcontains($msg.message-text, [&quot;sound&quot;, &quot;system&quot;], {&quot;mode&quot;:&quot;any&quot;})
270 ... where ftcontains($msg.message-text, {{&quot;speed&quot;, &quot;stand&quot;, &quot;customization&quot;}}, {&quot;mode&quot;:&quot;all&quot;})
271 ... where ftcontains($msg.message-text, let $keyword_list := [&quot;voice&quot;, &quot;system&quot;] return $keyword_list, {&quot;mode&quot;:&quot;all&quot;})
272 ... where ftcontains($msg.message-text, $keyword_list, {&quot;mode&quot;:&quot;any&quot;})
273</pre></div></div>
274<p>In the last example above, <tt>$keyword_list</tt> should evaluate to a string or an (un)ordered list of string value(s).</p>
275<p>The last <tt>FullTextOption</tt> parameter clarifies the given FTS request. If you omit the <tt>FullTextOption</tt> parameter, then the default value will be set for each possible option. Currently, we only have one option named <tt>mode</tt>. And as we extend the FTS feature, more options will be added. Please note that the format of <tt>FullTextOption</tt> is a record, thus you need to put the option(s) in a record <tt>{}</tt>. The <tt>mode</tt> option indicates whether the given FTS query is a conjunctive (AND) or disjunctive (OR) search request. This option can be either <tt>&#x201c;any&#x201d;</tt> or <tt>&#x201c;all&#x201d;</tt>. The default value for <tt>mode</tt> is <tt>&#x201c;all&#x201d;</tt>. If one specifies <tt>&#x201c;any&#x201d;</tt>, a disjunctive search will be conducted. For example, the following query will find documents whose <tt>message-text</tt> field contains &#x201c;sound&#x201d; or &#x201c;system&#x201d;, so a document will be returned if it contains either &#x201c;sound&#x201d;, &#x201c;system&#x201d;, or both of the keywords.</p>
276
277<div class="source">
278<div class="source">
279<pre> ... where ftcontains($msg.message-text, [&quot;sound&quot;, &quot;system&quot;], {&quot;mode&quot;:&quot;any&quot;})
280</pre></div></div>
281<p>The other option parameter,<tt>&#x201c;all&#x201d;</tt>, specifies a conjunctive search. The following examples will find the documents whose <tt>message-text</tt> field contains both &#x201c;sound&#x201d; and &#x201c;system&#x201d;. If a document contains only &#x201c;sound&#x201d; or &#x201c;system&#x201d; but not both, it will not be returned.</p>
282
283<div class="source">
284<div class="source">
285<pre> ... where ftcontains($msg.message-text, [&quot;sound&quot;, &quot;system&quot;], {&quot;mode&quot;:&quot;all&quot;})
286 ... where ftcontains($msg.message-text, [&quot;sound&quot;, &quot;system&quot;])
287</pre></div></div>
288<p>Currently AsterixDB doesn&#x2019;t (yet) support phrase searches, so the following query will not work.</p>
289
290<div class="source">
291<div class="source">
292<pre> ... where ftcontains($msg.message-text, &quot;sound system&quot;, {&quot;mode&quot;:&quot;any&quot;})
293</pre></div></div>
294<p>As a workaround solution, the following query can be used to achieve a roughly similar goal. The difference is that the following queries will find documents where <tt>$msg.message-text</tt> contains both &#x201c;sound&#x201d; and &#x201c;system&#x201d;, but the order and adjacency of &#x201c;sound&#x201d; and &#x201c;system&#x201d; are not checked, unlike in a phrase search. As a result, the query below would also return documents with &#x201c;sound system can be installed.&#x201d;, &#x201c;system sound is perfect.&#x201d;, or &#x201c;sound is not clear. You may need to install a new system.&#x201d;</p>
295
296<div class="source">
297<div class="source">
298<pre> ... where ftcontains($msg.message-text, [&quot;sound&quot;, &quot;system&quot;], {&quot;mode&quot;:&quot;all&quot;})
299 ... where ftcontains($msg.message-text, [&quot;sound&quot;, &quot;system&quot;])
300</pre></div></div></div>
301 </div>
302 </div>
303 </div>
304
305 <hr/>
306
307 <footer>
308 <div class="container-fluid">
309 <div class="row span12">Copyright &copy; 2017
310 <a href="https://www.apache.org/">The Apache Software Foundation</a>.
311 All Rights Reserved.
312
313 </div>
314
315 <?xml version="1.0" encoding="UTF-8"?>
316<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
317 feather logo, and the Apache AsterixDB project logo are either
318 registered trademarks or trademarks of The Apache Software
319 Foundation in the United States and other countries.
320 All other marks mentioned may be trademarks or registered
321 trademarks of their respective owners.</div>
322
323
324 </div>
325 </footer>
326 </body>
327</html>