-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add parent-child relationships to documentation
- Loading branch information
Showing
12 changed files
with
622 additions
and
249 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
192 changes: 192 additions & 0 deletions
192
docs/client-concepts/high-level/inference/routing-inference.asciidoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,192 @@ | ||
| :ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master | ||
|
|
||
| :github: https://github.com/elastic/elasticsearch-net | ||
|
|
||
| :nuget: https://www.nuget.org/packages | ||
|
|
||
| //// | ||
| IMPORTANT NOTE | ||
| ============== | ||
| This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/ClientConcepts/HighLevel/Inference/RoutingInference.doc.cs. | ||
| If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file, | ||
| please modify the original csharp file found at the link and submit the PR with that change. Thanks! | ||
| //// | ||
|
|
||
| [[routing-inference]] | ||
| === Routing inference | ||
|
|
||
| ==== Implicit conversion | ||
|
|
||
| You can always create a routing explicitly by relying on the implicit conversion from the following types | ||
|
|
||
| * `Int32` | ||
|
|
||
| * `Int64` | ||
|
|
||
| * `String` | ||
|
|
||
| * `Guid` | ||
|
|
||
| Methods and Properties that take an `Routing` can be passed any of these types and it will be implicitly | ||
| converted to an instance of `Routing` | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| Routing routingFromInt = 1; | ||
| Routing routingFromLong = 2L; | ||
| Routing routingFromString = "hello-world"; | ||
| Routing routingFromGuid = new Guid("D70BD3CF-4E38-46F3-91CA-FCBEF29B148E"); | ||
| Expect(1).WhenSerializing(routingFromInt); | ||
| Expect(2).WhenSerializing(routingFromLong); | ||
| Expect("hello-world").WhenSerializing(routingFromString); | ||
| Expect("d70bd3cf-4e38-46f3-91ca-fcbef29b148e").WhenSerializing(routingFromGuid); | ||
| ---- | ||
|
|
||
| ==== Inferring from a type | ||
|
|
||
| The real power of the `Routing` is in the inference rules (the default inferred routing for an object will be null). | ||
| Lets look at an example of this given the following POCO: | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| class MyDTO | ||
| { | ||
| public Guid Routing { get; set; } | ||
| public string Name { get; set; } | ||
| public string OtherName { get; set; } | ||
| } | ||
| ---- | ||
|
|
||
| By default NEST will try to find a property called `Routing` on the class using reflection | ||
| and create a cached delegate based on the property getter | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| var dto = new MyDTO | ||
| { | ||
| Routing = new Guid("D70BD3CF-4E38-46F3-91CA-FCBEF29B148E"), | ||
| Name = "x", | ||
| OtherName = "y" | ||
| }; | ||
| Expect(null).WhenInferringRoutingOn(dto); | ||
| ---- | ||
|
|
||
| Using connection settings, you can specify a property that NEST should use to infer Routing for the document. | ||
| Here we instruct NEST to infer the Routing for `MyDTO` based on its `Name` property | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| WithConnectionSettings(x => x | ||
| .InferMappingFor<MyDTO>(m => m | ||
| .RoutingProperty(p => p.Name) | ||
| ) | ||
| ).Expect("x").WhenInferringRoutingOn(dto); | ||
| ---- | ||
|
|
||
| IMPORTANT: Inference rules are cached __per__ `ConnectionSettings` instance. | ||
|
|
||
| Because the cache is per `ConnectionSettings` instance, we can create another `ConnectionSettings` instance | ||
| with different inference rules | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| WithConnectionSettings(x => x | ||
| .InferMappingFor<MyDTO>(m => m | ||
| .RoutingProperty(p => p.OtherName) | ||
| ) | ||
| ).Expect("y").WhenInferringRoutingOn(dto); | ||
| ---- | ||
|
|
||
| ==== JoinField | ||
|
|
||
| If your class has a property of type JoinField, NEST will automatically infer the parentid as the routing value. | ||
|
|
||
| The name of this property can be anything. Be sure the read the <<parent-child-relationships, section on Parent/Child relationships>> to get a complete | ||
| walkthrough on using Parent Child joins with NEST. | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| class MyOtherDTO | ||
| { | ||
| public JoinField SomeJoinField { get; set; } | ||
| public Guid Id { get; set; } | ||
| public string Name { get; set; } | ||
| public string OtherName { get; set; } | ||
| } | ||
| ---- | ||
|
|
||
| here we link this instance of `MyOtherDTO` with its parent id `"8080"` | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| var dto = new MyOtherDTO | ||
| { | ||
| SomeJoinField = JoinField.Link<MyOtherDTO>("8080"), | ||
| Id = new Guid("D70BD3CF-4E38-46F3-91CA-FCBEF29B148E"), | ||
| Name = "x", | ||
| OtherName = "y" | ||
| }; | ||
| Expect("8080").WhenInferringRoutingOn(dto); | ||
| ---- | ||
|
|
||
| Here we link this instance as the root (parent) of the relation. NEST infers that the default routing for this instance | ||
| should be the Id of the document itself. | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| dto = new MyOtherDTO | ||
| { | ||
| SomeJoinField = JoinField.Root<MyOtherDTO>(), | ||
| Id = new Guid("D70BD3CF-4E38-46F3-91CA-FCBEF29B148E"), | ||
| Name = "x", | ||
| OtherName = "y" | ||
| }; | ||
| Expect("d70bd3cf-4e38-46f3-91ca-fcbef29b148e").WhenInferringRoutingOn(dto); | ||
| ---- | ||
|
|
||
| ==== Precedence of ConnectionSettings | ||
|
|
||
| The routing property configured on `ConnectionSettings` always takes precedence. | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| WithConnectionSettings(x => x | ||
| .InferMappingFor<MyOtherDTO>(m => m | ||
| .RoutingProperty(p => p.OtherName) | ||
| ) | ||
| ).Expect("y").WhenInferringRoutingOn(dto); | ||
| class BadDTO | ||
| { | ||
| public JoinField SomeJoinField { get; set; } | ||
| public JoinField AnotherJoinField { get; set; } | ||
| public string ParentName { get; set; } | ||
| } | ||
| ---- | ||
|
|
||
| A class cannot contain more than one property of type JoinField, an exception is thrown in this case | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| var dto = new BadDTO | ||
| { | ||
| SomeJoinField = JoinField.Link<MyOtherDTO>("8080"), | ||
| AnotherJoinField = JoinField.Link<MyOtherDTO>("8081"), | ||
| ParentName = "my-parent" | ||
| }; | ||
| Action resolve = () => Expect("8080").WhenInferringRoutingOn(dto); | ||
| resolve.ShouldThrow<ArgumentException>().WithMessage("BadDTO has more than one JoinField property"); | ||
| ---- | ||
|
|
||
| unless you configure the ConnectionSettings to use an alternate property: | ||
|
|
||
| [source,csharp] | ||
| ---- | ||
| WithConnectionSettings(x => x | ||
| .InferMappingFor<BadDTO>(m => m | ||
| .RoutingProperty(p => p.ParentName) | ||
| ) | ||
| ).Expect("my-parent").WhenInferringRoutingOn(dto); | ||
| ---- | ||
|
|
Oops, something went wrong.