Skip to content

Commit 1238fe3

Browse files
russcamrusscam
committed
Indices.All and Indices.AllIndices documentation
Add verbatim and strict query usage to the documentation. Closes closes #1973
1 parent 7ffbc4f commit 1238fe3

File tree

7 files changed

+516
-98
lines changed

7 files changed

+516
-98
lines changed

‎docs/asciidoc/client-concepts/high-level/inference/indices-paths.asciidoc‎

Lines changed: 124 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,124 @@
1-
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/2.3
2-
3-
:github: https://github.com/elastic/elasticsearch-net
4-
5-
:nuget: https://www.nuget.org/packages
6-
7-
[[indices-paths]]
8-
== Indices paths
9-
10-
Some API's in Elasticsearch take one or many index name or a special `_all` marker to send the request to all the indices
11-
In nest this is encoded using `Indices`.
12-
13-
=== Implicit Conversion
14-
15-
Several types implicitly convert to `Indices`
16-
17-
[source,csharp]
18-
----
19-
Nest.Indices singleIndexFromString = "name";
20-
Nest.Indices multipleIndicesFromString = "name1, name2";
21-
Nest.Indices allFromString = "_all";
22-
Nest.Indices allWithOthersFromString = "_all, name2";
23-
singleIndexFromString.Match(
24-
all => all.Should().BeNull(),
25-
many => many.Indices.Should().HaveCount(1).And.Contain("name")
26-
);
27-
multipleIndicesFromString.Match(
28-
all => all.Should().BeNull(),
29-
many => many.Indices.Should().HaveCount(2).And.Contain("name2")
30-
);
31-
allFromString.Match(
32-
all => all.Should().NotBeNull(),
33-
many => many.Indices.Should().BeNull()
34-
);
35-
allWithOthersFromString.Match(
36-
all => all.Should().NotBeNull(),
37-
many => many.Indices.Should().BeNull()
38-
);
39-
----
40-
41-
[[nest-indices]]
42-
=== Using Nest.Indices
43-
44-
To ease creating `IndexName` or `Indices` from expressions, there is a static `Nest.Indices` class you can use
45-
46-
[source,csharp]
47-
----
48-
var all = Nest.Indices.All; <1>
49-
50-
var many = Nest.Indices.Index("name1", "name2"); <2>
51-
52-
var manyTyped = Nest.Indices.Index<Project>().And<CommitActivity>(); <3>
53-
54-
var singleTyped = Nest.Indices.Index<Project>();
55-
56-
var singleString = Nest.Indices.Index("name1");
57-
58-
var invalidSingleString = Nest.Indices.Index("name1, name2"); <4>
59-
----
60-
<1> Using `_all` indices
61-
62-
<2> specifying multiple indices using strings
63-
64-
<3> specifying multiple using types
65-
66-
<4> an **invalid** single index name
67-
1+
:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/2.3
2+
3+
:github: https://github.com/elastic/elasticsearch-net
4+
5+
:nuget: https://www.nuget.org/packages
6+
7+
[[indices-paths]]
8+
== Indices paths
9+
10+
Some APIs in Elasticsearch take one or many index name or a special `_all` marker to send the request to all the indices
11+
In nest this is encoded using `Indices`.
12+
13+
=== Implicit Conversion
14+
15+
Several types implicitly convert to `Indices`
16+
17+
[source,csharp]
18+
----
19+
Nest.Indices singleIndexFromString = "name";
20+
Nest.Indices multipleIndicesFromString = "name1, name2";
21+
Nest.Indices allFromString = "_all";
22+
Nest.Indices allWithOthersFromString = "_all, name2";
23+
singleIndexFromString.Match(
24+
all => all.Should().BeNull(),
25+
many => many.Indices.Should().HaveCount(1).And.Contain("name")
26+
);
27+
multipleIndicesFromString.Match(
28+
all => all.Should().BeNull(),
29+
many => many.Indices.Should().HaveCount(2).And.Contain("name2")
30+
);
31+
allFromString.Match(
32+
all => all.Should().NotBeNull(),
33+
many => many.Indices.Should().BeNull()
34+
);
35+
allWithOthersFromString.Match(
36+
all => all.Should().NotBeNull(),
37+
many => many.Indices.Should().BeNull()
38+
);
39+
----
40+
41+
[[nest-indices]]
42+
=== Using Nest.Indices
43+
44+
To ease creating `IndexName` or `Indices` from expressions, there is a static `Nest.Indices` class you can use
45+
46+
==== Specifying a single index
47+
48+
A single index can be specified using a CLR type or a string
49+
50+
[source,csharp]
51+
----
52+
var client = TestClient.GetInMemoryClient();
53+
54+
var singleString = Nest.Indices.Index("name1"); <1>
55+
56+
var singleTyped = Nest.Indices.Index<Project>(); <2>
57+
58+
ISearchRequest singleStringRequest = new SearchDescriptor<Project>().Index(singleString);
59+
60+
ISearchRequest singleTypedRequest = new SearchDescriptor<Project>().Index(singleTyped);
61+
62+
((IUrlParameter)singleStringRequest.Index).GetString(client.ConnectionSettings).Should().Be("name1");
63+
64+
((IUrlParameter)singleTypedRequest.Index).GetString(client.ConnectionSettings).Should().Be("project");
65+
66+
var invalidSingleString = Nest.Indices.Index("name1, name2"); <3>
67+
----
68+
<1> specifying a single index using a string
69+
70+
<2> specifying a single index using a type
71+
72+
<3> an **invalid** single index name
73+
74+
==== Specifying multiple indices
75+
76+
Similarly to a single index, multiple indices can be specified using multiple CLR types and multiple strings
77+
78+
[source,csharp]
79+
----
80+
var client = TestClient.GetInMemoryClient();
81+
82+
var manyStrings = Nest.Indices.Index("name1", "name2"); <1>
83+
84+
var manyTypes = Nest.Indices.Index<Project>().And<Developer>(); <2>
85+
86+
ISearchRequest manyStringRequest = new SearchDescriptor<Project>().Index(manyStrings);
87+
88+
ISearchRequest manyTypedRequest = new SearchDescriptor<Project>().Index(manyTypes);
89+
90+
((IUrlParameter)manyStringRequest.Index).GetString(client.ConnectionSettings).Should().Be("name1,name2");
91+
92+
((IUrlParameter)manyTypedRequest.Index).GetString(client.ConnectionSettings).Should().Be("project,devs"); <3>
93+
----
94+
<1> specifying multiple indices using strings
95+
96+
<2> specifying multiple indices using types
97+
98+
<3> The index names here come from the Connection Settings passed to `TestClient`. See the documentation on <<index-name-inference, Index Name Inference>> for more details.
99+
100+
==== Specifying All Indices
101+
102+
Elasticsearch allows searching across multiple indices using the special `_all` marker.
103+
104+
NEST exposes `_all` with `Indices.All` and `Indices.AllIndices`. Why expose it in two ways, you ask?
105+
Well, you may be using both `Nest.Indices` and `Nest.Types` in the same file and you may also be using C#6
106+
static imports too; in this scenario, `All` becomes ambiguous between `Indices.All` and `Types.All`, so the`_all` marker is exposed as `Indices.AllIndices` to alleviate this ambiguity
107+
108+
[source,csharp]
109+
----
110+
var client = TestClient.GetInMemoryClient();
111+
112+
var indicesAll = Nest.Indices.All;
113+
114+
var allIndices = Nest.Indices.AllIndices;
115+
116+
ISearchRequest indicesAllRequest = new SearchDescriptor<Project>().Index(indicesAll);
117+
118+
ISearchRequest allIndicesRequest = new SearchDescriptor<Project>().Index(allIndices);
119+
120+
((IUrlParameter)indicesAllRequest.Index).GetString(client.ConnectionSettings).Should().Be("_all");
121+
122+
((IUrlParameter)allIndicesRequest.Index).GetString(client.ConnectionSettings).Should().Be("_all");
123+
----
124+

‎docs/asciidoc/query-dsl.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,5 +143,7 @@ NEST exposes all of the query DSL endpoints available in Elasticsearch
143143

144144
include::{output-dir}/bool-dsl/bool-dsl.asciidoc[]
145145

146+
include::{output-dir}/verbatim/verbatim-and-strict-query-usage.asciidoc[]
147+
146148
include::query-dsl-usage.asciidoc[]
147149

‎docs/asciidoc/query-dsl/bool-dsl/bool-dsl.asciidoc‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ image::hadouken-indentation.jpg[hadouken indenting]
3232

3333
=== Operator Overloading
3434

35-
For this reason, NEST introduces **operator overloading** so complex bool queries become easier to write.
35+
For this reason, NEST introduces **operator overloading** so complex bool queries become easier to write.
3636
The previous example now becomes the following with the fluent API
3737

3838
[source,csharp]
@@ -48,14 +48,14 @@ or, using the object initializer syntax
4848
----
4949
searchResults = this.Client.Search<Project>(new SearchRequest<Project>
5050
{
51-
Query = new TermQuery { Field = "name", Value= "x" }
51+
Query = new TermQuery { Field = "name", Value= "x" }
5252
|| new TermQuery { Field = Field<Project>(p=>p.Name), Value = "y" }
5353
});
5454
----
5555

56-
A naive implementation of operator overloading would rewrite
56+
A naive implementation of operator overloading would rewrite
5757

58-
`term && term && term` to
58+
`term && term && term` to
5959

6060
....
6161
bool
@@ -67,12 +67,12 @@ bool
6767
|___term
6868
....
6969

70-
As you can image this becomes unwieldy quite fast the more complex a query becomes NEST can spot these and
70+
As you can image this becomes unwieldy quite fast the more complex a query becomes NEST can spot these and
7171
join them together to become a single bool query
7272

7373
....
7474
bool
75-
|___must
75+
|___must
7676
|___term
7777
|___term
7878
|___term
@@ -119,7 +119,7 @@ When combining multiple queries some or all possibly marked as `must_not` or `fi
119119

120120
....
121121
bool
122-
|___must
122+
|___must
123123
| |___term
124124
| |___term
125125
| |___term
@@ -148,14 +148,14 @@ Even more involved `term && term && term && !term && +term && +term` still only
148148

149149
....
150150
bool
151-
|___must
151+
|___must
152152
| |___term
153153
| |___term
154154
| |___term
155155
|
156156
|___must_not
157157
| |___term
158-
|
158+
|
159159
|___filter
160160
|___term
161161
|___term
@@ -180,7 +180,7 @@ c.Bool.MustNot.Should().HaveCount(1);
180180
c.Bool.Filter.Should().HaveCount(2);
181181
----
182182

183-
You can still mix and match actual bool queries with the bool DSL e.g`bool(must=term, term, term) && !term` would still merge into a single `bool` query.
183+
You can still mix and match actual bool queries with the bool DSL e.g`bool(must=term, term, term) && !term` would still merge into a single `bool` query.
184184

185185
[source,csharp]
186186
----
@@ -225,15 +225,15 @@ lastClause.Bool.Should.Should().HaveCount(3);
225225

226226
TIP: *add parentheses to force evaluation order*
227227

228-
Also note that using shoulds as boosting factors can be really powerful so if you need this
228+
Also note that using shoulds as boosting factors can be really powerful so if you need this
229229
always remember that you can mix and match an actual bool query with the bool dsl.
230230

231231
There is another subtle situation where NEST will not blindly merge 2 bool queries with only should clauses. Imagine the following:
232232

233-
`bool(should=term1, term2, term3, term4, minimum_should_match=2) || term5 || term6`
233+
`bool(should=term1, term2, term3, term4, minimum_should_match=2) || term5 || term6`
234234

235-
if NEST identified both sides of the OR operation as only containing `should` clauses and it would
236-
join them together it would give a different meaning to the `minimum_should_match` parameter of the first boolean query.
235+
if NEST identified both sides of the OR operation as only containing `should` clauses and it would
236+
join them together it would give a different meaning to the `minimum_should_match` parameter of the first boolean query.
237237
Rewriting this to a single bool with 5 `should` clauses would break because only matching on `term5` or `term6` should still be a hit.
238238

239239
[source,csharp]
@@ -265,8 +265,8 @@ nestedBool.Bool.Should.Should().HaveCount(4);
265265

266266
=== Locked bool queries
267267

268-
NEST will not combine `bool` queries if any of the query metadata is set e.g if metadata such as `boost` or `name` are set,
269-
NEST will treat these as locked
268+
NEST will not combine `bool` queries if any of the query metadata is set e.g if metadata such as `boost` or `name` are set,
269+
NEST will treat these as locked
270270

271271
Here we demonstrate that two locked `bool` queries are not combined
272272

@@ -317,7 +317,7 @@ nestedBool.Bool.Name.Should().Be(firstName);
317317

318318
[source,csharp]
319319
----
320-
assert(fluent.InvokeQuery(new QueryContainerDescriptor<Project>()));
320+
assert(fluent.Invoke(new QueryContainerDescriptor<Project>()));
321321
322322
assert((QueryContainer)ois);
323323
----

0 commit comments

Comments
 (0)