Skip to content

Commit c2591fd

Browse files
KodrAusKodrAus
committed
working on docs
1 parent cf13096 commit c2591fd

File tree

2 files changed

+102
-48
lines changed

2 files changed

+102
-48
lines changed

‎types/src/lib.rs

Lines changed: 65 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,67 @@
11
//! Elasticsearch Core Types
22
//!
33
//! A high-level implementation of the core types in Elasticsearch documents.
4-
//!
4+
//!
55
//! Types within this crate are self-contained and handle their own serialisation/deserialisation requirements.
66
//! Each type also supplies a `struct` for its [Put Mapping API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html) properties.
7-
//!
7+
//!
8+
//! # Types
9+
//!
10+
//! Types in Elasticsearch are a combination of _source_ and _mapping_.
11+
//! The source is the data (like `42` or `"my string"`) and the mapping is metadata about how to
12+
//! interpret and use the data (like the format of a date string).
13+
//!
14+
//! The approach `elastic_types` takes to types is to bundle the mapping up as a _Zero Sized Type_.
15+
//! This mapping type is then bound to a field as a generic parameter. For example:
16+
//!
17+
//! ```text
18+
//! ElasticString<DefaultStringMapping>
19+
//! ```
20+
//!
21+
//! The source is a `string` and the mapping is `DefaultStringMapping`.
22+
//!
23+
//! All Elasticsearch types implement the base `ElasticType<M: ElasticTypeMapping<F>, F>` trait
24+
//! where `M` is the mapping and `F` is a type-specific format.
25+
//!
26+
//! The following table illustrates the types provided by `elastic_types`:
27+
//!
28+
//! Elasticsearch Type | Rust Primitive (Default) | Crate | Rust Type (Custom) | Format Type
29+
//! ------------------ | ------------------------ | --------- | --------------------- | -----------
30+
//! `integer` | `i32` | `std` | `ElasticInteger<M>` | `()`
31+
//! `long` | `i64` | `std` | `ElasticLong<M>` | `()`
32+
//! `short` | `i16` | `std` | `ElasticShort<M>` | `()`
33+
//! `byte` | `i8` | `std` | `ElasticByte<M>` | `()`
34+
//! `float` | `f32` | `std` | `ElasticFloat<M>` | `()`
35+
//! `double` | `f64` | `std` | `ElasticDouble<M>` | `()`
36+
//! `string` | `String` | `std` | `ElasticString<M>` | `()`
37+
//! `date` | `DateTime` | `chrono` | `DateTime<F, M>` | `DateFormat`
38+
//! `object` | - | - | user-defined `struct` | `()`
39+
//!
40+
//! The following sections explain this table.
41+
//!
42+
//! ## Mapping
43+
//!
44+
//! Having the mapping available at compile-time makes it easy to write efficient generic methods
45+
//! that use type mapping.
46+
//!
47+
//! Where there's a `std` type that's equivalent to an Elasticsearch type (like `i32` for `integer`),
48+
//! a default mapping is implemented for that type.
49+
//! That means you can use primitives in your structs and have them mapped to the correct type in Elasticsearch.
50+
//! If you want to provide your own mapping for a `std` type, there's also a struct provided by `elastic_types`
51+
//! that wraps the `std` type but also takes an explicit mapping (like `ElasticInteger` for `i32`).
52+
//!
53+
//! Where there isn't a `std` type available (like `date`), an external crate is used and an implementation of
54+
//! that type is provided (like `DateTime`, which implements `chrono::DateLike + chrono::TimeLike`).
55+
//!
56+
//! ## Formats
57+
//!
58+
//! For some types (like `DateTime`), it's helpful to have an extra generic parameter that describes the
59+
//! `format` the data can take. For most types the format is `()`, because there aren't any alternative formats available.
60+
//!
861
//! # Examples
9-
//!
62+
//!
1063
//! Derive `ElasticType` on your Elasticsearch-mappable types:
11-
//!
64+
//!
1265
//! ```
1366
//! # #![feature(plugin, custom_derive)]
1467
//! # #![plugin(elastic_macros)]
@@ -18,34 +71,34 @@
1871
//! # use serde::{ Serialize, Deserialize };
1972
//! # use elastic_types::mapping::prelude::*;
2073
//! # use elastic_types::date::DateTime;
21-
//!
74+
//!
2275
//! #[derive(Default, Clone, Serialize, Deserialize)]
2376
//! pub struct MyType {
2477
//! pub my_date: DateTime,
2578
//! pub my_string: String,
2679
//! pub my_num: i32
2780
//! }
28-
//!
81+
//!
2982
//! #[derive(Default, Clone)]
3083
//! struct MyTypeMapping;
3184
//! impl ElasticObjectMapping for MyTypeMapping {
3285
//! fn data_type() -> &'static str {
3386
//! "object"
3487
//! }
35-
//!
88+
//!
3689
//! fn dynamic() -> Option<Dynamic> {
3790
//! Some(Dynamic::True)
3891
//! }
39-
//!
92+
//!
4093
//! fn enabled() -> Option<bool> {
4194
//! Some(false)
4295
//! }
43-
//!
96+
//!
4497
//! fn include_in_all() -> Option<bool> {
4598
//! Some(true)
4699
//! }
47100
//! }
48-
//!
101+
//!
49102
//! impl_object_mapping!(MyType, MyTypeMapping, "my_type", inner1, [my_date, my_string, my_num]);
50103
//! # impl serde::Serialize for MyType {
51104
//! # fn serialize<S>(&self, serializer: &mut S) -> Result<(), S::Error> where S: serde::Serializer {
@@ -60,7 +113,7 @@
60113
//! # fn main() {
61114
//! # }
62115
//! ```
63-
//!
116+
//!
64117
//! # Links
65118
//! - [Elasticsearch Doc](https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping.html)
66119
//! - [Github](https://github.com/KodrAus/elasticsearch-rs)
@@ -92,4 +145,4 @@ impl_mapping!(
92145
);
93146

94147
//TODO: This should map as T
95-
impl <T: serde::Serialize + serde::Deserialize> mapping::ElasticType<mapping::NullMapping, ()> for Vec<T> { }
148+
impl <T: serde::Serialize + serde::Deserialize> mapping::ElasticType<mapping::NullMapping, ()> for Vec<T> { }

‎types/src/mapping.rs

Lines changed: 37 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,38 @@
11
//! Base requirements for type mappings.
2-
//!
2+
//!
33
//! There are two kinds of types we can map in Elasticsearch; `field`/`data` types and `user-defined` types.
44
//! Either kind of type must implement `ElasticType`, which captures the mapping and possible formatting requirements as generic parameters.
55
//! Most of the work lives in the `ElasticTypeMapping`, which holds the serialisation requirements to convert a Rust type into an Elasticsearch mapping.
66
//! User-defined types must also implement `ElasticUserTypeMapping`, which maps the fields of a struct as properties, and treats the type as `nested` when used as a field itself.
7-
//!
7+
//!
88
//! # Notes
9-
//!
9+
//!
1010
//! Currently, there's a lot of ceremony around the type mapping. The reason for doing this with types instead of simple hashmaps is to try and capture type mapping using types themselves.
1111
//! This means more boilerplate while certain Rust features haven't landed yet ([specialisation](https://github.com/rust-lang/rust/issues/31844) and [negative trait bounds](https://github.com/rust-lang/rfcs/issues/1053)),
1212
//! but it also constrains the shapes that Elasticsearch types can take by using the Rust type system. That seems like a nice property.
13-
//!
13+
//!
1414
//! The mapping serialisation in general tries to limit allocations wherever possible, but more can be done to clean this up.
15-
//!
15+
//!
1616
//! # Links
1717
//! - [Field Types](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html)
1818
//! - [User-defined Types](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html)
1919
2020
pub mod prelude {
2121
//! Includes mapping types for all data types.
22-
//!
22+
//!
2323
//! This is a convenience module to make it easy to build mappings for multiple types without too many `use` statements.
24-
25-
pub use super::{
26-
ElasticType,
27-
ElasticTypeMapping,
28-
NullMapping,
29-
IndexAnalysis,
24+
25+
pub use super::{
26+
ElasticType,
27+
ElasticTypeMapping,
28+
NullMapping,
29+
IndexAnalysis,
3030
ElasticTypeMappingVisitor
3131
};
3232

3333
pub use ::object::*;
3434
pub use ::mappers::*;
35-
35+
3636
pub use ::date::mapping::*;
3737
pub use ::string::mapping::*;
3838
pub use ::number::mapping::*;
@@ -42,38 +42,39 @@ use std::marker::PhantomData;
4242
use serde;
4343

4444
/// The base representation of an Elasticsearch data type.
45-
///
46-
///
45+
///
46+
///
4747
/// `ElasticType` is the main `trait` you need to care about when building your own Elasticsearch types.
4848
/// Each type has two generic arguments that help define its mapping:
49-
///
49+
///
5050
/// - A mapping type, which implements `ElasticTypeMapping`
5151
/// - A format type, which is usually `()`. Types with multiple formats, like `DateTime`, can use the format in the type definition.
52-
///
52+
///
5353
/// ### Automatic
54-
///
54+
///
5555
/// The `elastic_macros` crate provides a plugin for you to automatically derive `ElasticType`:
56-
///
56+
///
5757
/// ```
5858
/// //TODO: Implement this
5959
/// ```
60-
///
60+
///
6161
/// ### Manual
62-
///
62+
///
6363
/// You can also derive `ElasticType` manually to get more control over the structure of your type mapping.
64-
///
64+
///
6565
/// ```
6666
/// //TODO: Implement this
6767
/// ```
68-
///
68+
///
6969
/// # Links
70-
///
70+
///
7171
/// - [Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html)
72-
pub trait ElasticType<T: ElasticTypeMapping<F>, F>
73-
where Self : serde::Serialize + serde::Deserialize { }
72+
pub trait ElasticType<T, F> where
73+
T: ElasticTypeMapping<F>,
74+
Self : serde::Serialize + serde::Deserialize { }
7475

7576
/// The base requirements for mapping an Elasticsearch data type.
76-
///
77+
///
7778
/// Each type has its own implementing structures with extra type-specific mapping parameters.
7879
/// If you're building your own Elasticsearch types, see `TypeMapping`, which is a specialization of `ElasticTypeMapping<()>`.
7980
pub trait ElasticTypeMapping<F>
@@ -82,7 +83,7 @@ where Self: Default + Clone + serde::Serialize {
8283
type Visitor : serde::ser::MapVisitor + Default;
8384

8485
/// An optional associated type that mappings may need.
85-
///
86+
///
8687
/// For example; the `DateFormat` trait on `DateTime`.
8788
type Format = F;
8889

@@ -130,15 +131,15 @@ impl serde::ser::MapVisitor for NullMappingVisitor {
130131
/// Should the field be searchable? Accepts `not_analyzed` (default) and `no`.
131132
#[derive(Debug, Clone, Copy)]
132133
pub enum IndexAnalysis {
133-
/// This option applies only to string fields, for which it is the default.
134-
/// The string field value is first analyzed to convert the string into terms
135-
/// (e.g. a list of individual words), which are then indexed.
136-
/// At search time, the query string is passed through (usually) the same analyzer
137-
/// to generate terms in the same format as those in the index.
134+
/// This option applies only to string fields, for which it is the default.
135+
/// The string field value is first analyzed to convert the string into terms
136+
/// (e.g. a list of individual words), which are then indexed.
137+
/// At search time, the query string is passed through (usually) the same analyzer
138+
/// to generate terms in the same format as those in the index.
138139
/// It is this process that enables full text search.
139140
Analyzed,
140-
/// Add the field value to the index unchanged, as a single term.
141-
/// This is the default for all fields that support this option except for string fields.
141+
/// Add the field value to the index unchanged, as a single term.
142+
/// This is the default for all fields that support this option except for string fields.
142143
/// `not_analyzed` fields are usually used with term-level queries for structured search.
143144
NotAnalyzed,
144145
/// Do not add this field value to the index. With this setting, the field will not be queryable.
@@ -175,4 +176,4 @@ impl <T: ElasticTypeMapping<()>> serde::ser::MapVisitor for ElasticTypeMappingVi
175176
where S: serde::Serializer {
176177
Ok(None)
177178
}
178-
}
179+
}

0 commit comments

Comments
 (0)