Skip to content

Commit 67a06e9

Browse files
russcamrusscam
committed
Asciidoc version of nest.azurewebsites.net
Move 1.x docs to elastic.co clients documentation
1 parent 708a9ce commit 67a06e9

File tree

101 files changed

+5535
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

101 files changed

+5535
-0
lines changed

‎docs/asciidoc/breaking-changes.asciidoc‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
:github: https://github.com/elastic/elasticsearch-net
2+
3+
[[breaking-changes]]
4+
== Breaking Changes
5+
6+
[float]
7+
== Elasticsearch 1.0
8+
9+
Elasticsearch 1.0 comes with it's own set of breaking changes which
10+
http://www.elasticsearch.org/guide/en/elasticsearch/reference/1.x/breaking-changes.html[are all documented in the elasticsearch documentation].
11+
This page describes breaking changes NEST introduces in its 1.0 release and to an extend how you should
12+
handle Elasticsearch 1.0 changes in your exisiting code base using NEST prior to NEST 1.0.
13+
14+
[float]
15+
== NEST 1.0
16+
17+
=== Strong Named Packages
18+
19+
Prior to 1.0 NEST came with a `NEST` and `NEST.Signed` nuget package.
20+
In 1.0 there is one package called `NEST` which is a signed strong named assembly.
21+
We follow the example of JSON.NET and only change our `AssemblyVersion` on major releases only
22+
update the `AssemblyFileVersion` for every release. This way you get most of the benefits of unsigned
23+
assemblies while still providing support for developers whose business guidelines mandates the usage of signed assemblies.
24+
25+
=== IElasticClient
26+
27+
The outer layer of NEST has been completely rewritten from scratch.
28+
Many calls will now have a different signature. Although the most common ones have been
29+
reimplemented as {github}/tree/1.x/src/Nest/ConvenienceExtensions[extensions methods].
30+
Two notable changes should be outlined though.
31+
32+
=== Renamed Get() to Source(), Removed GetFull()
33+
34+
When Martijn first wrote NEST back in 2010, he thought it would be handy if the Get() operation
35+
returned only the document, and if you wanted the full enveloped Elasticsearch response, you'd use `GetFull()`.
36+
This was rather confusing and on top of that Elasticsearch 1.0 now has it's own endpoint for getting JUST the document `_source`.
37+
Similarily `GetMany()` is now called `SourceMany()`.
38+
39+
=== Renamed QueryResponse to SearchResponse
40+
41+
The fact that `client.Search<T>()` returns a `QueryResponse<T>` and not a `SearchResponse<T>` never felt right,
42+
NEST 1.0 therefore renamed `QueryResponse<T>` to `SearchResponse<T>`
43+
44+
=== Renamed PutTemplateRaw()
45+
46+
to `.PutTemplate` and can be used as follows:
47+
48+
[source,csharp]
49+
----
50+
client.PutTemplate("template_name", s => s.Template("template_body"));
51+
----
52+
53+
=== Other Renames
54+
55+
* `RootObjectMappingDescriptor` => `PutMappingDescriptor<T>`
56+
* `BaseFilter` => `FilterContainer`
57+
* `BaseQuery` => `QueryContainer`
58+
* `SortDescriptor` => `SortFieldDescriptor`
59+
60+
=== Removed IResponse.Error
61+
62+
`IResponse.Error.Exception` no longer exists, it is inlined to `IResponse.OriginalException`.
63+
The Error property did not hold any information that was not available on IResponse.ConnectionStatus.
64+
65+
=== Removed IndexMany()
66+
67+
`IndexMany` no longer has an overload that takes `SimpleBulkParameters`.
68+
You are now required to use `Bulk()` directly if you need more fine grained control.
69+
70+
=== Removed MapFromAttributes()
71+
72+
Attributes are too limited in what they can specify, so `[ElasticType()]` can now only specify the type name and the id property.
73+
All the other annotations have been removed from `[ElasticType()]`. The properties on `[ElasticProperty()]` still exist and can be applied like this:
74+
75+
[source,csharp]
76+
----
77+
var x = this._client.CreateIndex(index, s => s
78+
.AddMapping<ElasticsearchProject>(m => m
79+
.MapFromAttributes()
80+
.DateDetection()
81+
.IndexAnalyzer())
82+
);
83+
----
84+
85+
Or in a separate put mapping call:
86+
87+
[source,csharp]
88+
----
89+
var response = client.Map<ElasticsearchProject>(m => m.MapFromAttributes()......);
90+
----
91+
92+
=== Response Shortcuts
93+
94+
Prior to 1.0, some calls directly returned a bool or value instead of the full enveloped Elasticsearch response.
95+
96+
i.e `client.IndexExists("myIndexName")` used to return a bool but should now be called like this:
97+
98+
[source,csharp]
99+
----
100+
client.IndexExists(i => i.Index("myIndexName")).Exists
101+
----
102+
103+
=== Alias Helpers
104+
105+
NEST 0.12.0 had some alias helpers, `SwapAlias()`, `GetIndicesPointingToAlias()`, etc. These have been removed in favor of just `Alias()` and `GetAliases()`.
106+
107+
=== Fields() vs SourceInclude()
108+
109+
Prior to Elasticsearch 1.0, you could specify to return only certain fields and they would return like this:
110+
111+
[source,javascript]
112+
----
113+
{
114+
"fields" : {
115+
"name": "NEST",
116+
"followers.firstName": ["Martijn", "John"]
117+
}
118+
}
119+
----
120+
121+
In many case this could be mapped to the type of DTO you give search (i.e in `.Search<DTO>()`). Elasticsearch 1.0 now always returns the fields as arrays.
122+
123+
[source,javascript]
124+
----
125+
{
126+
"fields" : {
127+
"name": ["NEST"],
128+
"followers.firstName": ["Martijn", "John"]
129+
}
130+
}
131+
----
132+
133+
Previously, Documents was a collection of `T` with just the specified fields filled in,
134+
other fields would be ``null or have their default value. Now, Documents is an empty collection.
135+
136+
Previously, `DocumentsWithMetaData` -> `Fields` would be an instance of ``T with just the specified fields filled in,
137+
other fields would be null or have their default value.
138+
Now, `Hits -> Fields` is (backed by) a dictionary containing only the specified fields.
139+
140+
NEST 1.0 still supports fields, but is now a bit more verbose in how it supports mapping the fields back:
141+
142+
[source,csharp]
143+
----
144+
var fields = _client.Get<DTO>(g => g
145+
.Id(4)
146+
.Fields(f => f.Name, f => f.Followers.First().FirstName)
147+
).Fields;
148+
149+
var name = fields.FieldValue<DTO, string>(f => f.Name);
150+
var list = fields.FieldValue<DTO, string>(f => f.Followers[0].FirstName);
151+
----
152+
153+
`name` and `list` are of type `string[]`
154+
155+
=== DocumentsWithMetaData
156+
157+
When you do a search with NEST 0.12, you'd get back a `QueryResponse<T>` with two ways to loop over your results.
158+
`.Documents` is an `IEnumerable<T>` and `.DocumentsWithMetaData` is and `IEnumerable<IHit<T>>` depending on your needs one of them might be easier to use.
159+
160+
Starting from NEST 1.0 `.DocumentsWithMetaData` is now called simply `.Hits`.
161+
162+
The old `.Hits` has been renamed to `HitsMetaData`.
163+
164+
=== int Properties
165+
166+
In quite a few places values that should have been `long` were mapped as `int` in NEST 0.12.0 which could be troublesome if you for instance have more than `2,147,483,647` matching documents. In my preperations for this release I helped port one of my former employees applications to Elasticsearch 1.1 and NEST 1.0 and found that this change had the most impact on the application and all of its models.
167+
168+
[float]
169+
== Found another breaking change?
170+
171+
If you found another breaking chage please let us know on {github}/issues[the github issues].
172+

‎docs/asciidoc/building.asciidoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:github: https://github.com/elastic/elasticsearch-net
2+
3+
== Building
4+
5+
Building `Elasticsearch.Net` and `NEST` should be super straightforward. Just fork and clone {github}[the repository on github]
6+
and open `Elasticsearch.sln` and press build.
7+
Alternatively you can run `build.bat` from the root to build everything the resulting assemblies will be exported to `build/output`.
8+
9+
NEST builds strong named assemblies but if you do not have the key the build script and
10+
`pre build events` are in place to generate one for you.
11+
The project very much believes in the http://www.khalidabuhakmeh.com/the-f5-manifesto-for-net-developers[F5 manifesto].
12+
13+
=== Build script
14+
The buildscript depends on quite a few tools
15+
16+
* FAKE - F# make to script the build
17+
* Nuget - used to install some of the dependencies
18+
* NUnit - to run the tests after build
19+
* sn.exe - used to check the validity of the signed assemblies during build/release procedures
20+
21+
All of these will be downloaded and installed locally in your repository the first time you run `build.bat` i the root of the project.
22+
23+
NOTE: none of these are needed to build from within Visual Studio
24+
25+
=== Build target
26+
27+
Running `build.bat` will default to running the `Build` target which will create certificates in the right place if they do not exist, build the application and run all the unit tests. The resulting assemblies are placed in `build/output`.
28+
29+
=== Release target
30+
31+
Running `build.bat Release versionnumber` will create nuget packages in `output/_packages`. This could be useful if you need a feature that is not yet released you can temporarily switch to local nuget packages.
32+
33+
Release will call the build target and in addition patch the assembly files, build the documentation files.

‎docs/asciidoc/contributing.asciidoc‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:github: https://github.com/elastic/elasticsearch-net
2+
3+
== Contributing
4+
5+
Contributing back to `Elasticsearch.Net` and `NEST` is very much appreciated!
6+
Whether you {github}/pull/536[feel the need to change one character] or have a go at
7+
{github}/pull/376[mapping new API's], no PR is too small or too big.
8+
9+
We do however ask you sign the http://www.elasticsearch.org/contributor-agreement/[Elasticsearch CLA] before we can accept pull requests from you.
10+
11+
=== Coding Styleguide
12+
13+
The source code uses tabs instead of spaces for indentation.
14+
15+
We highly recommend the http://visualstudiogallery.msdn.microsoft.com/c8bccfe2-650c-4b42-bc5c-845e21f96328[editorconfig visual studio]
16+
extension to automatically switch to tabs and back to your preferred/default settings for other projects.
17+
18+
In most cases we won't shun a PR just because it uses the wrong indentation settings though it'll be **very** much appreciated!
19+

‎docs/asciidoc/elasticsearch-net/building-requests.asciidoc‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
[[building-requests]]
2+
== Building Requests
3+
4+
`Elasticsearch.Net` maps **all** the Elasticsearch API endpoints to methods. The reason it can do this is because all these methods are generated from
5+
https://github.com/elasticsearch/elasticsearch/tree/master/rest-api-spec/api[the official client REST specification].
6+
This specification documents all the URL's (paths and querystrings) but does not map any of the API request and response bodies.
7+
8+
[source,csharp]
9+
----
10+
client.GetSource("myindex","mytype","1",qs=>qs
11+
.Routing("routingvalue")
12+
);
13+
----
14+
15+
Which will do a `GET` request on `/myindex/mytype/1/_source?routing=routingvalue`.
16+
All the methods and arguments are fully documented based on the documentation of the specification.
17+
18+
As you can see, `Elasticsearch.Net` also strongly types the querystring parameters it knows exist on an endpoint with full Intellisense documentation.
19+
Unknown querystring parameters can still be added:
20+
21+
[source,csharp]
22+
----
23+
client.GetSource("myindex","mytype","1",qs=>qs
24+
.Routing("routingvalue")
25+
.Add("key","value")
26+
);
27+
----
28+
29+
The querystring parameter is always optional.
30+
31+
=== Providing a Request Body
32+
33+
Some endpoints need a request body which can be passed in a couple of ways
34+
35+
==== String
36+
37+
[source,csharp]
38+
----
39+
var myJson = @"{ ""hello"" : ""world"" }";
40+
41+
client.Index("myindex","mytype","1", myJson);
42+
-----
43+
44+
This will call `POST` on `/myindex/mytype/1` with the provided string `myJson` passed verbatim as the request body
45+
46+
==== (Anonymous) Object
47+
48+
[source,csharp]
49+
----
50+
var myJson = new { hello = "world" };
51+
client.Index("myindex","mytype","1", myJson);
52+
----
53+
54+
This will call `POST` on `/myindex/mytype/1` where `myJson` will be serialized by the registered `ISerializer`
55+
56+
NOTE: if you need `PUT` semantics `IndexPut()` also exists. `Elasticsearch.Net` exposes all the endpoints with all the allowed HTTP methods.
57+
58+
==== IEnumerable<object>
59+
60+
Some API endpoints in Elasticsearch follow a strict special json format.
61+
62+
....
63+
line_of_json_with_no_enters \n
64+
json_payload_with_enters
65+
line_of_json_with_no_enters \n
66+
json_payload_with_enters
67+
line_of_json_with_no_enters \n
68+
json_payload_with_enters
69+
.....
70+
71+
Examples of such endpoints are the http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/docs-bulk.html#docs-bulk[bulk api].
72+
In `Elasticsearch.Net` you can call these with
73+
74+
[source,csharp]
75+
----
76+
var bulk = new object[]
77+
{
78+
new { index = new { _index = "test", _type="type", _id = "1" }},
79+
new { name = "my object's name" }
80+
};
81+
82+
client.Bulk(bulk);
83+
----
84+
85+
`Elasticsearch.Net` will know not to serialize the passed object as `[]` but instead serialize each item seperately and join them up with `\n`.
86+
No request in Elasticsearch expects an array as the root object for the request.
87+
88+
89+

0 commit comments

Comments
 (0)