Skip to content

Improve Index name inference docs #3968

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 23, 2019
Merged

Improve Index name inference docs #3968

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 85 additions & 41 deletions docs/client-concepts/high-level/inference/index-name-inference.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,103 +23,147 @@ NEST has a number of ways in which the index name(s) can be specified
==== Default Index name on Connection Settings

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

[source,csharp]
----
var settings = new ConnectionSettings()
.DefaultIndex("defaultindex");
var resolver = new IndexNameResolver(settings);
var index = resolver.Resolve<Project>();
index.Should().Be("defaultindex");
.DefaultIndex("defaultindex"); <1>

var client = new ElasticClient(settings);
var searchResponse = client.Search<Project>();
----
<1> set the default index

will send a search request to the API endpoint

[source,javascript]
----
"http://localhost:9200/defaultindex/_search"
----

[[index-name-type-mapping]]
==== Mapping an Index name for a .NET type
==== Index name for a .NET type

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

[source,csharp]
----
var settings = new ConnectionSettings()
.DefaultMappingFor<Project>(m => m
.IndexName("projects")
);
var resolver = new IndexNameResolver(settings);
var index = resolver.Resolve<Project>();
index.Should().Be("projects");

var client = new ElasticClient(settings);
var searchResponse = client.Search<Project>();
----

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

[source,csharp]
[source,javascript]
----
var settings = new ConnectionSettings()
.DefaultMappingFor<Project>(m => m
.IndexName("projects")
);
var resolver = new IndexNameResolver(settings);
var index = resolver.Resolve<Project>();
index.Should().Be("projects");
"http://localhost:9200/projects/_search"
----

An index name for a POCO provided using `.MapDefaultTypeIndices()` or `.DefaultMappingFor<T>()` **will take precedence** over
`.DefaultMappingFor<T>()` can also be used to specify other defaults for a POCO, including
property names, property to use for the document id, amongst others.

An index name for a POCO provided using `.DefaultMappingFor<T>()` **will take precedence** over
the default index name set on `ConnectionSettings`. This way, the client can be configured with a default index to use if no
index is specified, and a specific index to use for different POCO types.

[source,csharp]
----
var settings = new ConnectionSettings()
.DefaultIndex("defaultindex")
.DefaultIndex("defaultindex") <1>
.DefaultMappingFor<Project>(m => m
.IndexName("projects")
.IndexName("projects") <2>
);
var resolver = new IndexNameResolver(settings);
var index = resolver.Resolve<Project>();
index.Should().Be("projects");

var client = new ElasticClient(settings);

var projectSearchResponse = client.Search<Project>();
----
<1> a default index to use, when no other index can be inferred

<2> a index to use when `Project` is the target POCO type

will send a search request to the API endpoint

[source,javascript]
----
"http://localhost:9200/projects/_search"
----

but

[source,csharp]
----
var objectSearchResponse = client.Search<object>();
----

will send a search request to the API endpoint

[source,javascript]
----
"http://localhost:9200/defaultindex/_search"
----

==== Explicitly specifying Index name on the request

For API calls that expect an index name, the index name can be explicitly provided
For API calls that expect an index name, an index name can be explicitly provided
on the request

[source,csharp]
----
var client = TestClient.Default;
var response = client.Search<Project>(s => s.Index("some-other-index")); <1>
var requestUri = response.ApiCall.Uri;
var settings = new ConnectionSettings();
var client = new ElasticClient(settings);

requestUri.Should().NotBeNull();
requestUri.LocalPath.Should().StartWith("/some-other-index/");
var response = client.Search<Project>(s => s
.Index("some-other-index") <1>
);
----
<1> Provide the index name on the request

will send a search request to the API endpoint

[source,javascript]
----
"http://localhost:9200/some-other-index/_search"
----

When an index name is provided on a request, it **will take precedence** over the default
index name and any index name specified for the POCO type using `.MapDefaultTypeIndices()` or
`.DefaultMappingFor<T>()`
index name specified on `ConnectionSettings`, _and_ any index name specified for the POCO
using `.DefaultMappingFor<T>()`. The following example will send a search request
to the same API endpoint as the previous example

[source,csharp]
----
var client = new ElasticClient(new AlwaysInMemoryConnectionSettings()
var settings = new ConnectionSettings()
.DefaultIndex("defaultindex")
.DefaultMappingFor<Project>(m => m
.IndexName("projects")
));
);

var response = client.Search<Project>(s => s.Index("some-other-index")); <1>
var client = new ElasticClient(settings);

response.ApiCall.Uri.Should().NotBeNull();
response.ApiCall.Uri.LocalPath.Should().StartWith("/some-other-index/");
var response = client.Search<Project>(s => s
.Index("some-other-index")
);
----
<1> Provide the index name on the request

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

. Index name specified on the request

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

. Default index name specified on `ConnectionSettings`

[IMPORTANT]
--
If no index can be determined for a request that requires an index, the client will throw
an exception to indicate that this is the case.

--

Loading