Skip to content

Commit cfbbb98

Browse files
russcamrusscam
committed
Add documentation for percolate query usage
1 parent d1e5346 commit cfbbb98

File tree

9 files changed

+398
-27
lines changed

9 files changed

+398
-27
lines changed

‎docs/asciidoc/query-dsl/specialized/percolate/percolate-query-usage.asciidoc

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
[[percolate-query-usage]]
8+
== Percolate Query Usage
9+
10+
The percolate query can be used to match queries stored in an index.
11+
The percolate query itself contains the document that will be used as query to match with the stored queries.
12+
13+
IMPORTANT: In order for the percolate query to work, the index in which your stored queries reside must contain
14+
a mapping for documents that you wish to percolate, so that they are parsed correctly at query time.
15+
16+
See the Elasticsearch documentation on {ref_current}/query-dsl-percolate-query.html[percolate query] for more details.
17+
18+
In this example, we have a document stored with a `query` field that is mapped as a `percolator` type. This field
19+
contains a `match` query.
20+
21+
[source,csharp]
22+
----
23+
foreach (var index in values.Values)
24+
{
25+
this.Client.CreateIndex(index, c => c
26+
.Mappings(m => m
27+
.Map<Project>(mm => mm.AutoMap()
28+
.Properties(Seeder.ProjectProperties)
29+
)
30+
.Map<PercolatedQuery>(mm => mm.AutoMap()
31+
.Properties(Seeder.PercolatedQueryProperties)
32+
)
33+
)
34+
);
35+
36+
this.Client.Index(new PercolatedQuery
37+
{
38+
Id = PercolatorId,
39+
Query = new QueryContainer(new MatchQuery
40+
{
41+
Field = Infer.Field<Project>(f => f.LeadDeveloper.FirstName),
42+
Query = "Martijn"
43+
})
44+
}, d => d.Index(index));
45+
46+
this.Client.Refresh(index);
47+
}
48+
----
49+
50+
=== Fluent DSL Example
51+
52+
[source,csharp]
53+
----
54+
f =>
55+
f.Query(QueryFluent).Index(CallIsolatedValue).AllTypes()
56+
----
57+
58+
=== Object Initializer Syntax Example
59+
60+
[source,csharp]
61+
----
62+
new SearchRequest<PercolatedQuery>(CallIsolatedValue, Types.All)
63+
{
64+
Query = this.QueryInitializer
65+
}
66+
----
67+
68+
[source,javascript]
69+
.Example json output
70+
----
71+
{
72+
"percolator": {
73+
"document_type": "project",
74+
"document": {
75+
"name": "Koch, Collier and Mohr",
76+
"state": "BellyUp",
77+
"startedOn": "2015-01-01T00:00:00",
78+
"lastActivity": "0001-01-01T00:00:00",
79+
"leadDeveloper": {
80+
"gender": "Male",
81+
"id": 0,
82+
"firstName": "Martijn",
83+
"lastName": "Laarman"
84+
},
85+
"location": {
86+
"lat": 42.1523,
87+
"lon": -80.321
88+
}
89+
}
90+
}
91+
}
92+
----
93+
94+
=== Fluent DSL Example
95+
96+
[source,csharp]
97+
----
98+
q
99+
.Percolate(p => p
100+
.DocumentType(typeof(Project))
101+
.Document(Project.Instance)
102+
)
103+
----
104+
105+
=== Object Initializer Syntax Example
106+
107+
[source,csharp]
108+
----
109+
new PercolateQuery
110+
{
111+
DocumentType = typeof(Project),
112+
Document = Project.Instance,
113+
}
114+
----
115+
116+
=== Handling Responses
117+
118+
[source,csharp]
119+
----
120+
response.Total.Should().BeGreaterThan(0);
121+
response.Hits.Should().NotBeNull();
122+
response.Hits.Count().Should().BeGreaterThan(0);
123+
var match = response.Documents.First();
124+
match.Id.Should().Be(PercolatorId);
125+
((IQueryContainer)match.Query).Match.Should().NotBeNull();
126+
----
127+
128+
[[percolate-an-existing-document]]
129+
[float]
130+
== Percolate an existing document
131+
132+
Instead of specifying a the source of the document being percolated, the source can also be
133+
retrieved from an already stored document. The percolate query will then internally execute a get request to fetch that document.
134+
135+
The required fields to percolate an existing document are:
136+
137+
* `index` in which the document resides
138+
139+
* `type` of the document
140+
141+
* `id` of the document
142+
143+
* `document_type` type / mapping of the document
144+
145+
See the Elasticsearch documentation on {ref_current}/query-dsl-percolate-query.html[percolate query] for more details.
146+
147+
[source,csharp]
148+
----
149+
foreach (var index in values.Values)
150+
{
151+
this.Client.CreateIndex(index, c => c
152+
.Mappings(m => m
153+
.Map<Project>(mm => mm.AutoMap()
154+
.Properties(Seeder.ProjectProperties)
155+
)
156+
.Map<PercolatedQuery>(mm => mm.AutoMap()
157+
.Properties(Seeder.PercolatedQueryProperties)
158+
)
159+
)
160+
);
161+
162+
this.Client.Index(new PercolatedQuery
163+
{
164+
Id = PercolatorId,
165+
Query = new QueryContainer(new MatchQuery
166+
{
167+
Field = Infer.Field<Project>(f => f.LeadDeveloper.FirstName),
168+
Query = "Martijn"
169+
})
170+
}, d => d.Index(index));
171+
172+
this.Client.Index(Project.Instance);
173+
this.Client.Refresh(Nest.Indices.Index(index).And<Project>());
174+
}
175+
----
176+
177+
=== Fluent DSL Example
178+
179+
[source,csharp]
180+
----
181+
f =>
182+
f.Query(QueryFluent).Index(CallIsolatedValue).AllTypes()
183+
----
184+
185+
=== Object Initializer Syntax Example
186+
187+
[source,csharp]
188+
----
189+
new SearchRequest<PercolatedQuery>(CallIsolatedValue, Types.All)
190+
{
191+
Query = this.QueryInitializer
192+
}
193+
----
194+
195+
[source,javascript]
196+
.Example json output
197+
----
198+
{
199+
"percolator": {
200+
"type": "project",
201+
"index": "project",
202+
"id": "Durgan LLC",
203+
"document_type": "project"
204+
}
205+
}
206+
----
207+
208+
=== Fluent DSL Example
209+
210+
[source,csharp]
211+
----
212+
q
213+
.Percolate(p => p
214+
.Type<Project>()
215+
.Index<Project>()
216+
.Id(Project.Instance.Name)
217+
.DocumentType<Project>() <1>
218+
)
219+
----
220+
<1> specify the `type`, `index`, `id` and `document_type` of the document to fetch, to percolate.
221+
222+
=== Object Initializer Syntax Example
223+
224+
[source,csharp]
225+
----
226+
new PercolateQuery
227+
{
228+
Type = typeof(Project),
229+
Index = IndexName.From<Project>(),
230+
Id = Project.Instance.Name,
231+
DocumentType = typeof(Project)
232+
}
233+
----
234+
235+
=== Handling Responses
236+
237+
[source,csharp]
238+
----
239+
response.Total.Should().BeGreaterThan(0);
240+
response.Hits.Should().NotBeNull();
241+
response.Hits.Count().Should().BeGreaterThan(0);
242+
var match = response.Documents.First();
243+
match.Id.Should().Be(PercolatorId);
244+
((IQueryContainer)match.Query).Match.Should().NotBeNull();
245+
----
246+

‎paket.lock

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
NUGET
2-
remote: https://www.nuget.org/api/v2
2+
remote: http://api.nuget.org/v3/index.json
33
specs:
44
AsciiDocNet (1.0.0-alpha3)
5+
SemanticVersioning (0.6.17)
6+
ShellProgressBar (3.0)
7+
remote: https://www.nuget.org/api/v2
8+
specs:
59
Bogus (3.0.5-beta-2)
610
Newtonsoft.Json (>= 8.0.2) - framework: >= net40, dnx451, dnxcore50
711
System.ComponentModel (>= 4.0.1-beta-23516) - framework: dnxcore50
@@ -348,10 +352,6 @@ NUGET
348352
System.Threading.Tasks (>= 4.0) - framework: dnxcore50
349353
xunit.abstractions (>= 2.0) - framework: dnxcore50
350354
xunit.extensibility.core (2.1) - framework: >= net45, dnx451, dnxcore50, monoandroid, monotouch, xamarinios, winv4.5, wpv8.0, wpav8.1
351-
remote: http://api.nuget.org/v3/index.json
352-
specs:
353-
SemanticVersioning (0.6.17)
354-
ShellProgressBar (3.0)
355355

356356
GROUP build
357357
NUGET

‎src/CodeGeneration/Nest.Litterateur/AsciiDoc/GeneratedAsciidocVisitor.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,17 +54,17 @@ public override void Visit(Document document)
5454
_newDocument.Attributes.Add(attributeEntry);
5555
}
5656

57-
if (!document.Attributes.Any(a => a.Name == "ref_current"))
57+
if (document.Attributes.All(a => a.Name != "ref_current"))
5858
{
59-
_newDocument.Attributes.Add(new AttributeEntry("ref_current", "https://www.elastic.co/guide/en/elasticsearch/reference/current"));
59+
_newDocument.Attributes.Add(new AttributeEntry("ref_current", "https://www.elastic.co/guide/en/elasticsearch/reference/master"));
6060
}
6161

62-
if (!document.Attributes.Any(a => a.Name == "github"))
62+
if (document.Attributes.All(a => a.Name != "github"))
6363
{
6464
_newDocument.Attributes.Add(new AttributeEntry("github", "https://github.com/elastic/elasticsearch-net"));
6565
}
6666

67-
if (!document.Attributes.Any(a => a.Name == "nuget"))
67+
if (document.Attributes.All(a => a.Name != "nuget"))
6868
{
6969
_newDocument.Attributes.Add(new AttributeEntry("nuget", "https://www.nuget.org/packages"));
7070
}

‎src/Nest/CommonAbstractions/Infer/Id/IdExtensions.cs

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Linq;
4+
using System.Threading.Tasks;
5+
6+
namespace Nest
7+
{
8+
public static class IdExtensions
9+
{
10+
public static bool IsConditionless(this Id id)
11+
{
12+
return id == null || (id.Value == null && id.Document == null);
13+
}
14+
}
15+
}

‎src/Nest/CommonAbstractions/Infer/TypeName/TypeNameExtensions.cs

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,9 @@
22
{
33
public static class TypeNameExtensions
44
{
5-
65
public static bool IsConditionless(this TypeName marker)
76
{
87
return marker == null || marker.Name.IsNullOrEmpty() && marker.Type == null;
98
}
109
}
11-
}
10+
}

‎src/Nest/QueryDsl/Abstractions/Container/QueryContainerDescriptor.cs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -459,7 +459,9 @@ public QueryContainer Regexp(Func<RegexpQueryDescriptor<T>, IRegexpQuery> select
459459
this.Assign(selector, (query, container) => container.Regexp = query);
460460

461461
/// <summary>
462-
/// Function score query
462+
/// The function_score query allows you to modify the score of documents that are retrieved by a query.
463+
/// This can be useful if, for example, a score function is computationally expensive and it is
464+
/// sufficient to compute the score on a filtered set of documents.
463465
/// </summary>
464466
/// <returns></returns>
465467
public QueryContainer FunctionScore(Func<FunctionScoreQueryDescriptor<T>, IFunctionScoreQuery> selector) =>

0 commit comments

Comments
 (0)