Module elastic::types::document

Base requirements for indexable document mappings.

Structures that can be indexed in Elasticsearch should implement DocumentType. The DocumentType is composed of typical mapping metadata, as well as the mapping for each of its properties.

Documents can be mapped as indexable types, or as an object field on another type.

Examples

Define your Elasticsearch types using Plain Old Rust Structures.

Derive Mapping

Mapping can be generated by deriving ElasticType on a struct:

#[derive(Serialize, ElasticType)]
pub struct MyType {
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

This will produce the following field mapping:

{
    "type": "nested",
    "properties": {
        "my_date": {
            "type": "date",
            "format": "basic_date_time"
        },
        "my_string": {
            "type": "text",
            "fields": {
                "keyword":{
                    "type":"keyword",
                    "ignore_above":256
                }
            }
        },
        "my_num": {
            "type": "integer"
        }
    }
}

It's also possible to adjust the mapping using the #[elastic] attribute.

Specifying a default index name

Documents will default to using an index name that's derived from the name of the Rust type. The #[elastic(index)] attribute can be used to set the index name that documents belong to:

#[derive(Serialize, ElasticType)]
#[elastic(index = "my-index")]
pub struct MyType {
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

Not all documents have a static index that's the same for all instances though. For index names that depend on document fields, use the #[elastic(index(expr = "function"))] attribute:

#[derive(Serialize, ElasticType)]
#[elastic(index(expr = "self.index()"))]
pub struct MyType {
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

impl MyType {
    fn index(&self) -> String {
        format!("my-index-{}", self.my_date)
    }
}

Specifying a type name

Documents will default to using _doc as the type name. The #[elastic(ty)] attribute can be used to set the type name that documents belong to:

#[derive(Serialize, ElasticType)]
#[elastic(ty = "my-type")]
pub struct MyType {
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

Specifying an id field

Documents will default to not using a field as an id. The #[elastic(id)] attribute can be used to specify an id field:

#[derive(Serialize, ElasticType)]
pub struct MyType {
    #[elastic(id)]
    pub my_id: String,
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

The field annotated with #[elastic(id)] must satisfy impl Into<Cow<'_, str>>. An id can also be calculated based on an expression function using the #[elastic(id(expr = "expression"))] attribute:

#[derive(Serialize, ElasticType)]
#[elastic(id(expr = "self.id()"))]
pub struct MyType {
    pub my_id: i32,
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

impl MyType {
    fn id(&self) -> String {
        self.my_id.to_string()
    }
}

An expression can also be used on fields, where an identifier with the same name as the field can be used:

#[derive(Serialize, ElasticType)]
pub struct MyType {
    #[elastic(id(expr = "my_id.to_string()"))]
    pub my_id: i32,
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

Override Default Mapping Properties

You can override the mapping meta properties for an object by providing your own mapping type with #[elastic(mapping="{TypeName}")]:

#[derive(Serialize, ElasticType)]
#[elastic(mapping="MyTypeMapping")]
pub struct MyType {
    pub my_date: Date<DefaultDateMapping>,
    pub my_string: String,
    pub my_num: i32
}

#[derive(Default)]
pub struct MyTypeMapping;
impl ObjectMapping for MyTypeMapping {
    type Properties = MyType;

    fn data_type() -> &'static str { OBJECT_DATATYPE }
}

This will produce the following field mapping:

{
    "type": "object",
    "properties": {
        "my_date": {
            "type": "date",
            "format": "basic_date_time"
        },
        "my_string": {
            "type": "text",
            "fields": {
                "keyword":{
                    "type":"keyword",
                    "ignore_above":256
                }
            }
        },
        "my_num": {
            "type": "integer"
        }
    }
}

Ignore or Rename Fields

You can then serialise type mappings with #[serde] attributes:

#[derive(ElasticType, Serialize)]
pub struct MyType {
    #[serde(rename="my_renamed_date")]
    pub my_date: Date<DefaultDateMapping>,
    #[serde(skip_serializing)]
    pub ignored: String,
    pub my_num: i32
}

NOTE: Fields with a #[serde(skip_deserializing)] attribute will still be mapped, because they can still be indexed in Elasticsearch.

Limitations

Automatically deriving mapping has the following limitations:

• Generics aren't supported by auto deriving. So you can't #[derive(ElasticType)] on MyType<T>.
• Mapping types can't be shared. This is because they need to map the type fields, so are specific to that type. So you can't share MyTypeMapping between MyType and MyOtherType.

Links

• Field Types
• Document Types

Modules

mapping	Mapping for Elasticsearch document types.
prelude	Includes all types for document types.

Structs

EmptyPropertiesMapping	Mapping for an anonymous json object.
FieldDocumentMapping	A wrapper type for serialising user types as fields.
Id
Index
IndexDocumentMapping	A wrapper type for serialising user types.
Type
ValueObjectMapping	Mapping for an anonymous json object.

Constants

DEFAULT_DOC_TYPE

The default name for document types in a single document index.

Traits

DocumentType	An indexable Elasticsearch type.
StaticIndex	An indexable Elasticsearch type with a static index.
StaticType	An indexable Elasticsearch type with a static document type.