You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2019/09/01 17:35:17 UTC
svn commit: r1049500 - in /websites/staging/jena/trunk/content: ./
documentation/query/text-query.html
Author: buildbot
Date: Sun Sep 1 17:35:17 2019
New Revision: 1049500
Log:
Staging update by buildbot for jena
Modified:
websites/staging/jena/trunk/content/ (props changed)
websites/staging/jena/trunk/content/documentation/query/text-query.html
Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sun Sep 1 17:35:17 2019
@@ -1 +1 @@
-1860944
+1866242
Modified: websites/staging/jena/trunk/content/documentation/query/text-query.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/query/text-query.html (original)
+++ websites/staging/jena/trunk/content/documentation/query/text-query.html Sun Sep 1 17:35:17 2019
@@ -282,7 +282,10 @@ illustrates creating an in-memory datase
</ul>
</li>
<li><a href="#configuration">Configuration</a><ul>
-<li><a href="#text-dataset-assembler">Text Dataset Assembler</a></li>
+<li><a href="#text-dataset-assembler">Text Dataset Assembler</a><ul>
+<li><a href="#lists-of-indexed-properties">Lists of Indexed Properties</a></li>
+</ul>
+</li>
<li><a href="#configuring-an-analyzer">Configuring an analyzer</a></li>
<li><a href="#configuration-by-code">Configuration by Code</a></li>
<li><a href="#graph-specific-indexing">Graph-specific Indexing</a></li>
@@ -429,7 +432,7 @@ points below.</p>
<p>The most general form is:</p>
-<div class="codehilite"><pre> <span class="p">(</span> ?<span class="n">s</span> ?<span class="n">score</span> ?<span class="n">literal</span> ?<span class="n">g</span> <span class="p">)</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">property</span> <span class="s">'query string'</span> <span class="n">limit</span> <span class="s">'lang:xx'</span> <span class="s">'highlight:yy'</span> <span class="p">)</span>
+<div class="codehilite"><pre> <span class="p">(</span> ?<span class="n">s</span> ?<span class="n">score</span> ?<span class="n">literal</span> ?<span class="n">g</span> <span class="p">)</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">property</span><span class="o">*</span> <span class="s">'query string'</span> <span class="n">limit</span> <span class="s">'lang:xx'</span> <span class="s">'highlight:yy'</span> <span class="p">)</span>
</pre></div>
@@ -444,7 +447,7 @@ points below.</p>
<tbody>
<tr>
<td>property</td>
-<td>(optional) URI (including prefix name form)</td>
+<td>(zero or more) property URIs (including prefix name form)</td>
</tr>
<tr>
<td>query string</td>
@@ -467,15 +470,48 @@ points below.</p>
<p>The <code>property</code> URI is only necessary if multiple properties have been
indexed and the property being searched over is not the <a href="#entity-map-definition">default field
of the index</a>.</p>
+<p>Since 3.13.0, <code>property</code> may be a list of zero or more (prior to 3.13.0 zero or one) Lucene indexed properties, or a defined
+<a href="#lists-of-indexed-properties"><code>text:propList</code> of indexed properties</a>.
+The meaning is an <code>OR</code> of searches on a variety of properties. This can be used in place of SPARQL level <code>UNION</code>s of
+individual <code>text:query</code>s. For example, instead of:</p>
+<div class="codehilite"><pre><span class="n">select</span> ?<span class="n">foo</span> <span class="n">where</span> <span class="p">{</span>
+ <span class="p">{</span>
+ <span class="p">(</span>?<span class="n">s</span> ?<span class="n">sc</span> ?<span class="n">lit</span><span class="p">)</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">label</span> "<span class="n">some</span> <span class="n">query</span>" <span class="p">).</span>
+ <span class="p">}</span>
+ <span class="n">union</span>
+ <span class="p">{</span>
+ <span class="p">(</span>?<span class="n">s</span> ?<span class="n">sc</span> ?<span class="n">lit</span><span class="p">)</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">skos</span><span class="p">:</span><span class="n">altLabel</span> "<span class="n">some</span> <span class="n">query</span>" <span class="p">).</span>
+ <span class="p">}</span>
+ <span class="n">union</span>
+ <span class="p">{</span>
+ <span class="p">(</span>?<span class="n">s</span> ?<span class="n">sc</span> ?<span class="n">lit</span><span class="p">)</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">skos</span><span class="p">:</span><span class="n">prefLabel</span> "<span class="n">some</span> <span class="n">query</span>" <span class="p">).</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>it can be more performant to push the unions into the Lucene query by rewriting as:</p>
+<div class="codehilite"><pre><span class="p">(</span>?<span class="n">s</span> ?<span class="n">sc</span> ?<span class="n">lit</span><span class="p">)</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">rdfs</span><span class="p">:</span><span class="n">label</span> <span class="n">skos</span><span class="p">:</span><span class="n">prefLabel</span> <span class="n">skos</span><span class="p">:</span><span class="n">altLabel</span> "<span class="n">some</span> <span class="n">query</span>" <span class="p">)</span>
+</pre></div>
+
+
+<p>which creates a Lucene query:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">altLabel</span><span class="p">:</span>"<span class="n">some</span> <span class="n">query</span>" <span class="n">OR</span> <span class="n">prefLabel</span><span class="p">:</span>"<span class="n">some</span> <span class="n">query</span>" <span class="n">OR</span> <span class="n">label</span><span class="p">:</span>"<span class="n">some</span> <span class="n">query</span>"<span class="p">)</span>
+</pre></div>
+
+
<p>The <code>query string</code> syntax conforms to the underlying index <a href="http://lucene.apache.org/core/6_4_1/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description">Lucene</a>
or
-<a href="https://www.elastic.co/guide/en/elasticsearch/reference/5.2/query-dsl.html">Elasticsearch</a>. In the case of Lucene the syntax is restricted to <code>Terms</code>, <code>Term modifiers</code>, <code>Boolean Operators</code> applied to <code>Terms</code>, and <code>Grouping</code> of terms. <em>No use of <code>Fields</code> within the <code>query string</code> is supported.</em></p>
+<a href="https://www.elastic.co/guide/en/elasticsearch/reference/5.2/query-dsl.html">Elasticsearch</a>. In the case of Lucene the
+syntax is restricted to <code>Terms</code>, <code>Term modifiers</code>, <code>Boolean Operators</code> applied to <code>Terms</code>, and <code>Grouping</code> of terms. <em>No
+use of <code>Fields</code> within the <code>query string</code> is supported.</em></p>
<p>The optional <code>limit</code> indicates the maximum hits to be returned by Lucene.</p>
<p>The <code>lang:xx</code> specification is an optional string, where <em>xx</em> is
a BCP-47 language tag. This restricts searches to field values that were originally
indexed with the tag <em>xx</em>. Searches may be restricted to field values with no
language tag via <code>"lang:none"</code>. </p>
-<p>The <code>highlight:yy</code> specification is an optional string where <em>yy</em> are options that control the highlighting of search result literals. See <a href="#highlighting">below</a> for details.</p>
+<p>The <code>highlight:yy</code> specification is an optional string where <em>yy</em> are options that control the highlighting of search
+result literals. See <a href="#highlighting">below</a> for details.</p>
<p>If both <code>limit</code> and one or more of <code>lang:xx</code> or <code>highlight:yy</code> are present, then <code>limit</code> must precede these arguments.</p>
<p>If only the query string is required, the surrounding <code>( )</code> <em>may be</em> omitted.</p>
<h4 id="output-arguments">Output arguments:<a class="headerlink" href="#output-arguments" title="Permanent link">¶</a></h4>
@@ -513,7 +549,8 @@ latter case the search is restricted to
subject. The <em>score</em>, <em>literal</em> and <em>graph URI</em> <strong>must</strong> be variables.</p>
<h3 id="query-strings">Query strings<a class="headerlink" href="#query-strings" title="Permanent link">¶</a></h3>
<p>There are several points that need to be considered when formulating
-SPARQL queries using the Lucene interface. As mentioned above, in the case of Lucene the <code>query string</code> syntax is restricted to <code>Terms</code>, <code>Term modifiers</code>, <code>Boolean Operators</code> applied to <code>Terms</code>, and <code>Grouping</code> of terms. </p>
+SPARQL queries using the Lucene interface. As mentioned above, in the case of Lucene the <code>query string</code> syntax is
+restricted to <code>Terms</code>, <code>Term modifiers</code>, <code>Boolean Operators</code> applied to <code>Terms</code>, and <code>Grouping</code> of terms. </p>
<p><strong>No <em>explicit</em> use of <code>Fields</code> within the <code>query string</code> is supported.</strong></p>
<h4 id="simple-queries">Simple queries<a class="headerlink" href="#simple-queries" title="Permanent link">¶</a></h4>
<p>The simplest use of the jena-text Lucene integration is:</p>
@@ -925,7 +962,8 @@ indexed as well: <a href="#building-a-te
text:analyzer <span class="p">[</span> a text:StandardAnalyzer <span class="p">]</span> <span class="p">;</span>
text:queryAnalyzer <span class="p">[</span> a text:KeywordAnalyzer <span class="p">]</span> <span class="p">;</span>
text:queryParser text:AnalyzingQueryParser <span class="p">;</span>
- text:defineAnalyzers <span class="p">[</span> <span class="m">.</span> <span class="m">.</span> <span class="m">.</span> <span class="p">]</span> <span class="p">;</span>
+ text:propLists <span class="p">(</span> <span class="p">[</span> <span class="m">.</span> <span class="m">.</span> <span class="m">.</span> <span class="p">]</span> <span class="m">.</span> <span class="m">.</span> <span class="m">.</span> <span class="p">)</span> <span class="p">;</span>
+ text:defineAnalyzers <span class="p">(</span> <span class="p">[</span> <span class="m">.</span> <span class="m">.</span> <span class="m">.</span> <span class="p">]</span> <span class="m">.</span> <span class="m">.</span> <span class="m">.</span> <span class="p">)</span> <span class="p">;</span>
text:multilingualSupport true <span class="p">;</span> <span class="c1"># optional</span>
<span class="m">.</span>
<span class="c1"># Entity map (see documentation for other options)</span>
@@ -984,6 +1022,9 @@ used to analyze the query string. If not
<p><code>text:queryParser</code> is optional and specifies an <a href="#alternative-query-parsers">alternative query parser</a></p>
</li>
<li>
+<p><code>text:propLists</code> is optional and allows to specify <a href="#lists-of-indexed-properties">lists of indexed properties</a> for use in <code>text:query</code></p>
+</li>
+<li>
<p><code>text:defineAnalyzers</code> is optional and allows specification of <a href="#defined-analyzers">additional analyzers, tokenizers and filters</a></p>
</li>
<li>
@@ -1020,6 +1061,34 @@ to identify the dataset URI to be assemb
dataset, one for the base data. Therefore, the application needs to
identify the text dataset by it's URI
<code>http://localhost/jena_example/#text_dataset</code>.</p>
+<h4 id="lists-of-indexed-properties">Lists of Indexed Properties<a class="headerlink" href="#lists-of-indexed-properties" title="Permanent link">¶</a></h4>
+<p>Since 3.13.0, an optional <code>text:TextIndexLucene</code> feature, <code>text:propLists</code> allows to define lists of Lucene indexed
+properties that may be used in <code>text:query</code>s. For example:</p>
+<div class="codehilite"><pre><span class="n">text</span><span class="o">:</span><span class="n">propLists</span> <span class="o">(</span>
+ <span class="o">[</span> <span class="n">text</span><span class="o">:</span><span class="n">propListProp</span> <span class="n">ex</span><span class="o">:</span><span class="n">labels</span> <span class="o">;</span>
+ <span class="n">text</span><span class="o">:</span><span class="n">props</span> <span class="o">(</span> <span class="n">skos</span><span class="o">:</span><span class="n">prefLabel</span>
+ <span class="n">skos</span><span class="o">:</span><span class="n">altLabel</span>
+ <span class="n">rdfs</span><span class="o">:</span><span class="n">label</span> <span class="o">)</span> <span class="o">;</span>
+ <span class="o">]</span>
+ <span class="o">[</span> <span class="n">text</span><span class="o">:</span><span class="n">propListProp</span> <span class="n">ex</span><span class="o">:</span><span class="n">workStmts</span> <span class="o">;</span>
+ <span class="n">text</span><span class="o">:</span><span class="n">props</span> <span class="o">(</span> <span class="n">ex</span><span class="o">:</span><span class="n">workColophon</span>
+ <span class="n">ex</span><span class="o">:</span><span class="n">workAuthorshipStatement</span>
+ <span class="n">ex</span><span class="o">:</span><span class="n">workEditionStatement</span> <span class="o">)</span> <span class="o">;</span>
+ <span class="o">]</span>
+<span class="o">)</span> <span class="o">;</span>
+</pre></div>
+
+
+<p>The <code>text:propLists</code> is a list of <em>property list</em> definitions. Each <em>property list</em> defines a new property,
+<code>text:propListProp</code> that will be used to refer to the list in a <code>text:query</code>, for example, <code>ex:labels</code> and
+<code>ex:workStmts</code>, above. The <code>text:props</code> is a list of Lucene indexed properties that will be searched over when the
+<em>property list</em> property is referred to in a <code>text:query</code>. For example:</p>
+<div class="codehilite"><pre>?<span class="n">s</span> <span class="n">text</span><span class="p">:</span><span class="n">query</span> <span class="p">(</span> <span class="n">ex</span><span class="p">:</span><span class="n">labels</span> "<span class="n">some</span> <span class="n">text</span>" <span class="p">)</span> <span class="p">.</span>
+</pre></div>
+
+
+<p>will request Lucene to search for documents representing triples, ?s ?p ?o, where ?p is one of: <code>rdfs:label</code> OR
+<code>skos:prefLbael</code> OR <code>skos:altLabel</code>, matching the query string.</p>
<h3 id="entity-map-definition">Entity Map definition<a class="headerlink" href="#entity-map-definition" title="Permanent link">¶</a></h3>
<p>A <code>text:EntityMap</code> has several properties that condition what is indexed, what information is stored, and
what analyzers are used.</p>