Skip to content

MInor Doc Updates #749

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.

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 10 commits into from
Jul 8, 2014
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Binary file removed new_docs/contents/.DS_Store
Binary file not shown.
10 changes: 5 additions & 5 deletions new_docs/contents/breaking-changes.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
---
template: layout.jade
title: Breaking changes
title: Breaking Changes
menusection: concepts
menuitem: breaking-changes
---

#Breaking changes
#Breaking Changes

## Elasticsearch 1.0

Elasticsearch 1.0 comes with it's own set of breaking changes which [are all documented in the elasticsearch documentation](http://www.elasticsearch.org/guide/en/elasticsearch/reference/1.x/breaking-changes.html). This page describes breaking changes NEST introduces in its 1.0 release and to an extend how you should handle Elasticsearch 1.0 changes in your exisiting code base using NEST prior to NEST 1.0.

## NEST 1.0

### Strong named packages
### Strong Named Packages

Prior to 1.0 NEST came with a `NEST` and `NEST.Signed` nuget package. In 1.0 there is one package called `NEST` which is a signed strong named assembly. We follow the example of JSON.NET and only change our `AssemblyVersion` on major releases only update the `AssemblyFileVersion` for every release. This way you get most of the benefits of unsigned assemblies while still providing support for developers who's business guidelines mandates the usage of signed assemblies.

Expand All @@ -38,7 +38,7 @@ to `PutMappingDescriptor<T>`

IResponse.Error.Exception no longer exists, it is inlined to IResponse.OriginalException. The Error property did not hold any information that was not available on IResponse.ConnectionStatus.

### Response shortcuts
### Response Shortcuts

Prior to 1.0 some calls directly returned a bool or value instead of the full envelopped Elasticsearch response.

Expand All @@ -63,7 +63,7 @@ Or in a separate put mapping call:

var response = this._client.Map<ElasticsearchProject>(m=>m.MapFromAttributes()......);

#### Alias helpers
#### Alias Helpers

NEST 0.12.0 had some alias helpers, `SwapAlias()`, `GetIndicesPointingToAlias()` these have been removed in favor of just `Alias()` and `GetAliases()`. Especially the later could benefit from some extension methods that make the common use cases a bit easier to program with. These did not make the beta release.

Expand Down
4 changes: 2 additions & 2 deletions new_docs/contents/elasticsearch-net/building-requests.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ menuitem: esnet-building-requests

This section decribes how to build requests to Elasticsearch.

## Calling an API endpoint
## Calling an API Endpoint

`Elasticsearch.Net` maps **all** the `Elasticsearch` API endpoints to methods. The reason it can do this is because all these methods are generated from
[the official client rest specification](https://github.com/elasticsearch/elasticsearch/tree/master/rest-api-spec/api). This specification documents all
Expand All @@ -32,7 +32,7 @@ Unknown querystring parameters can still be added:

The querystring parameter is always optional.

## Providing request body
## Providing Request Body

Some endpoints need a request body this can be passed in a couple of ways.

Expand Down
2 changes: 1 addition & 1 deletion new_docs/contents/elasticsearch-net/errors.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
template: layout.jade
title: Quick Start
title: Errors
menusection:
menuitem: esnet-errors
---
Expand Down
6 changes: 3 additions & 3 deletions new_docs/contents/elasticsearch-net/handling-responses.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
template: layout.jade
title: Handling responses
title: Handling Responses
menusection:
menuitem: esnet-handling-responses
---

# Handling responses
# Handling Responses

Describes how to handle the the response objects from `Elasticsearch.Net`

Expand Down Expand Up @@ -34,7 +34,7 @@ A `byte[]` representation of the response from elasticsearch, only set when `Exp
#### Response
The deserialized `T` object representing the response.

## Typed API calls
## Typed API Calls

`Elasticsearch.Net` does not provide typed objects representing the responses this is up to the developer to map.

Expand Down
4 changes: 2 additions & 2 deletions new_docs/contents/nest/handling-responses.markdown
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
template: layout.jade
title: Connecting
title: Handling Responses
menusection: concepts
menuitem: handling-responses
---


# Handling responses
# Handling Responses


All the return objects from API calls in NEST client implement:
Expand Down
14 changes: 7 additions & 7 deletions new_docs/contents/nest/index-type-inference.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
template: layout.jade
title: Connecting
title: Type/Index Inference
menusection: concepts
menuitem: index-type-inference
---
Expand Down Expand Up @@ -40,11 +40,11 @@ As noted in the [quick start](/nest/quick-start.html) you can always pass **expl
.Ttl("1m")
);

This will index the document using `/another-index/another-type/1-should-not-be-the-id?refresh=true&&ttl=1m` as the url.
This will index the document using `/another-index/another-type/1-should-not-be-the-id?refresh=true&ttl=1m` as the url.

There are a couple of places within NEST where inference comes in to play

## Index name inference
## Index Name Inference

Whenever an explicit index name is not provided NEST will look to see if the type has it's own default index name on the connection settings.

Expand All @@ -56,12 +56,12 @@ Whenever an explicit index name is not provided NEST will look to see if the typ
// searches in /my-type-index/mytype/_search
client.Search<MyType>()

// searches in /my-default-index/mytype/_search
// searches in /my-default-index/person/_search
client.Search<Person>()

`MyType` defaults to `my-type-index` because it is explicitly configured but `Person` will default to the global fallback `my-default-index`.

## Type name inference
## Type Name Inference

Whenever NEST needs a type name but is not given one explicitly it will use the given CLR type to infer it's Elasticsearch type name.

Expand Down Expand Up @@ -90,7 +90,7 @@ Prior to NEST 1.0 typenames were by default lowercased AND pluralized, if you wa

settings.PluralizeTypeNames();

## Property name inference
## Property Name Inference
In many places `NEST` allows you to pass property names and JSON paths as C# expressions i.e

.Query(q=>q.Term(p=>p.Followers.First().FirstName, "martijn"))
Expand All @@ -107,7 +107,7 @@ This will leave property names untouched.

Properties marked with `[ElasticAttibute(Name="")]` or `[JsonProperty(Name="")]` will pass the configured name verbatim.

## Id inference
## Id Inference

Whenever an object is passed that needs to specify an id (i.e index, bulk operations) the object is inspected to see if it has an `Id` property and if so, that value will be used.

Expand Down
2 changes: 1 addition & 1 deletion new_docs/contents/nest/searching.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
template: layout.jade
title: Connecting
title: Searching
menusection: concepts
menuitem: searching
---
Expand Down
14 changes: 7 additions & 7 deletions new_docs/contents/nest/writing-queries.markdown
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
template: layout.jade
title: Connecting
title: Writing Queries
menusection: concepts
menuitem: writing-queries
---
Expand All @@ -14,7 +14,7 @@ One of the most important things to grasp when using Nest is how to write querie
///EXAMPLE HERE
);

## Raw strings
## Raw Strings
Although not preferred by me personally, many folks like to build their own JSON strings and just pass that along.

.QueryRaw("\"match_all\" : { }")
Expand All @@ -25,7 +25,7 @@ Nest does not modify this in anyway and just writes this straight into the JSON
## Query DSL
The preferred way to write queries, since it gives you alot of cool features.

### Lambda expressions
### Lambda Expressions
.Query(q=>q
.Term(p=>p.Name, "NEST")
)
Expand All @@ -44,7 +44,7 @@ Of course if you need to pass the property name as string NEST will allow you to
.Term("followers.firstName", "martijn")
)

### Static query/filter generator.
### Static Query/Filter Generator
Sometimes you'll need to resuse a filter or query often. To aid with this you can also write queries like this:

var termQuery = Query<ElasticSearchProject>
Expand All @@ -61,7 +61,7 @@ Sometimes you'll need to resuse a filter or query often. To aid with this you ca

Similarly `Filter<T>.[Filter]()` methods exist for filters.

### Boolean queries
### Boolean Queries
As can be seen in the previous example writing out boolean queries can turn into a really tedious and verbose effort. Luckily NEST supports bitwise operators and so we can rewrite the previous as such:

.Query(q=>q.MatchAll() && termQuery)
Expand Down Expand Up @@ -96,7 +96,7 @@ You can mix and match this to any level of complexity until it satisfies your qu

Will query all php clients except 'Elastica` or where the name equals `NEST`.

#### Clean output support
#### Clean Output Support
Normally writing three boolean must clauses looks like this (psuedo code)

must
Expand All @@ -114,7 +114,7 @@ A naive implemenation of the bitwise operators would make all the queries sent t

This degrades rather rapidly and makes inspecting generated queries quite a chore. NEST does it's best to detect these cases and will always write them in the first, cleaner form.

## Conditionless queries
## Conditionless Queries

Writing complex boolean queries is one thing, but more often then not you'll want to make decisions on how to query based on user input.

Expand Down