Skip to content

Commit 6c6d932

Browse files
russcamrusscam
authored
Improve Index name inference docs (#3968)
This commit improves the readability of the index name inference documentation, and updates paragraphs in line with client changes. Closes #3914
1 parent f7e4fa6 commit 6c6d932

File tree

2 files changed

+209
-87
lines changed

2 files changed

+209
-87
lines changed

‎docs/client-concepts/high-level/inference/index-name-inference.asciidoc‎

Lines changed: 85 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -23,103 +23,147 @@ NEST has a number of ways in which the index name(s) can be specified
2323
==== Default Index name on Connection Settings
2424

2525
A default index name can be specified on `ConnectionSettings` using `.DefaultIndex()`.
26-
This is the default index name to use when no other index name can be resolved for a request
26+
This is the default index name to use, when no other index name can be resolved for a request
2727

2828
[source,csharp]
2929
----
3030
var settings = new ConnectionSettings()
31-
.DefaultIndex("defaultindex");
32-
var resolver = new IndexNameResolver(settings);
33-
var index = resolver.Resolve<Project>();
34-
index.Should().Be("defaultindex");
31+
.DefaultIndex("defaultindex"); <1>
32+
33+
var client = new ElasticClient(settings);
34+
var searchResponse = client.Search<Project>();
35+
----
36+
<1> set the default index
37+
38+
will send a search request to the API endpoint
39+
40+
[source,javascript]
41+
----
42+
"http://localhost:9200/defaultindex/_search"
3543
----
3644

3745
[[index-name-type-mapping]]
38-
==== Mapping an Index name for a .NET type
46+
==== Index name for a .NET type
3947

40-
A index name can be mapped for CLR types using `.MapDefaultTypeIndices()` on `ConnectionSettings`.
48+
An index name can be mapped for a _Plain Old CLR Object_ (POCO) using `.DefaultMappingFor<T>()` on `ConnectionSettings`
4149

4250
[source,csharp]
4351
----
4452
var settings = new ConnectionSettings()
4553
.DefaultMappingFor<Project>(m => m
4654
.IndexName("projects")
4755
);
48-
var resolver = new IndexNameResolver(settings);
49-
var index = resolver.Resolve<Project>();
50-
index.Should().Be("projects");
56+
57+
var client = new ElasticClient(settings);
58+
var searchResponse = client.Search<Project>();
5159
----
5260

53-
`.DefaultMappingFor<T>()` can also be used to specify the index name, as well as be used
54-
to specify the type name and POCO property that should be used as the id for the document
61+
will send a search request to the API endpoint
5562

56-
[source,csharp]
63+
[source,javascript]
5764
----
58-
var settings = new ConnectionSettings()
59-
.DefaultMappingFor<Project>(m => m
60-
.IndexName("projects")
61-
);
62-
var resolver = new IndexNameResolver(settings);
63-
var index = resolver.Resolve<Project>();
64-
index.Should().Be("projects");
65+
"http://localhost:9200/projects/_search"
6566
----
6667

67-
An index name for a POCO provided using `.MapDefaultTypeIndices()` or `.DefaultMappingFor<T>()` **will take precedence** over
68+
`.DefaultMappingFor<T>()` can also be used to specify other defaults for a POCO, including
69+
property names, property to use for the document id, amongst others.
70+
71+
An index name for a POCO provided using `.DefaultMappingFor<T>()` **will take precedence** over
6872
the default index name set on `ConnectionSettings`. This way, the client can be configured with a default index to use if no
6973
index is specified, and a specific index to use for different POCO types.
7074

7175
[source,csharp]
7276
----
7377
var settings = new ConnectionSettings()
74-
.DefaultIndex("defaultindex")
78+
.DefaultIndex("defaultindex") <1>
7579
.DefaultMappingFor<Project>(m => m
76-
.IndexName("projects")
80+
.IndexName("projects") <2>
7781
);
78-
var resolver = new IndexNameResolver(settings);
79-
var index = resolver.Resolve<Project>();
80-
index.Should().Be("projects");
82+
83+
var client = new ElasticClient(settings);
84+
85+
var projectSearchResponse = client.Search<Project>();
86+
----
87+
<1> a default index to use, when no other index can be inferred
88+
89+
<2> a index to use when `Project` is the target POCO type
90+
91+
will send a search request to the API endpoint
92+
93+
[source,javascript]
94+
----
95+
"http://localhost:9200/projects/_search"
96+
----
97+
98+
but
99+
100+
[source,csharp]
101+
----
102+
var objectSearchResponse = client.Search<object>();
103+
----
104+
105+
will send a search request to the API endpoint
106+
107+
[source,javascript]
108+
----
109+
"http://localhost:9200/defaultindex/_search"
81110
----
82111

83112
==== Explicitly specifying Index name on the request
84113

85-
For API calls that expect an index name, the index name can be explicitly provided
114+
For API calls that expect an index name, an index name can be explicitly provided
86115
on the request
87116

88117
[source,csharp]
89118
----
90-
var client = TestClient.Default;
91-
var response = client.Search<Project>(s => s.Index("some-other-index")); <1>
92-
var requestUri = response.ApiCall.Uri;
119+
var settings = new ConnectionSettings();
120+
var client = new ElasticClient(settings);
93121
94-
requestUri.Should().NotBeNull();
95-
requestUri.LocalPath.Should().StartWith("/some-other-index/");
122+
var response = client.Search<Project>(s => s
123+
.Index("some-other-index") <1>
124+
);
96125
----
97126
<1> Provide the index name on the request
98127

128+
will send a search request to the API endpoint
129+
130+
[source,javascript]
131+
----
132+
"http://localhost:9200/some-other-index/_search"
133+
----
134+
99135
When an index name is provided on a request, it **will take precedence** over the default
100-
index name and any index name specified for the POCO type using `.MapDefaultTypeIndices()` or
101-
`.DefaultMappingFor<T>()`
136+
index name specified on `ConnectionSettings`, _and_ any index name specified for the POCO
137+
using `.DefaultMappingFor<T>()`. The following example will send a search request
138+
to the same API endpoint as the previous example
102139

103140
[source,csharp]
104141
----
105-
var client = new ElasticClient(new AlwaysInMemoryConnectionSettings()
142+
var settings = new ConnectionSettings()
106143
.DefaultIndex("defaultindex")
107144
.DefaultMappingFor<Project>(m => m
108145
.IndexName("projects")
109-
));
146+
);
110147
111-
var response = client.Search<Project>(s => s.Index("some-other-index")); <1>
148+
var client = new ElasticClient(settings);
112149
113-
response.ApiCall.Uri.Should().NotBeNull();
114-
response.ApiCall.Uri.LocalPath.Should().StartWith("/some-other-index/");
150+
var response = client.Search<Project>(s => s
151+
.Index("some-other-index")
152+
);
115153
----
116-
<1> Provide the index name on the request
117154

118155
In summary, the order of precedence for determining the index name for a request is
119156

120157
. Index name specified on the request
121158

122-
. Index name specified for the generic type parameter in the request using `.MapDefaultTypeIndices()` or `.DefaultMappingFor<T>()`
159+
. Index name specified for the generic type parameter in the request using `.DefaultMappingFor<T>()`
123160

124161
. Default index name specified on `ConnectionSettings`
125162

163+
[IMPORTANT]
164+
--
165+
If no index can be determined for a request that requires an index, the client will throw
166+
an exception to indicate that this is the case.
167+
168+
--
169+

0 commit comments

Comments
 (0)