Auto mapping

When creating a mapping either when creating an index or through the Put Mapping API, NEST offers a feature called auto mapping that can automagically infer the correct Elasticsearch field datatypes from the CLR POCO property types you are mapping.

We’ll look at the features of auto mapping with a number of examples. For this, we’ll define two POCOs, Company, which has a name and a collection of Employees, and Employee which has various properties of different types, and itself has a collection of Employee types.

public class Company
{
    public string Name { get; set; }
    public List<Employee> Employees { get; set; }
}

public class Employee
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Salary { get; set; }
    public DateTime Birthday { get; set; }
    public bool IsManager { get; set; }
    public List<Employee> Employees { get; set; }
    public TimeSpan Hours { get; set; }
}

Auto mapping can take the pain out of having to define a manual mapping for all properties on the POCO

var descriptor = new CreateIndexDescriptor("myindex")
    .Mappings(ms => ms
        .Map<Company>(m => m.AutoMap()) 
        .Map<Employee>(m => m.AutoMap()) 
    );

{
  "mappings": {
    "company": {
      "properties": {
        "employees": {
          "properties": {
            "birthday": {
              "type": "date"
            },
            "employees": {
              "properties": {},
              "type": "object"
            },
            "firstName": {
              "type": "string"
            },
            "hours": {
              "type": "long"
            },
            "isManager": {
              "type": "boolean"
            },
            "lastName": {
              "type": "string"
            },
            "salary": {
              "type": "integer"
            }
          },
          "type": "object"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "employee": {
      "properties": {
        "birthday": {
          "type": "date"
        },
        "employees": {
          "properties": {},
          "type": "object"
        },
        "firstName": {
          "type": "string"
        },
        "hours": {
          "type": "long"
        },
        "isManager": {
          "type": "boolean"
        },
        "lastName": {
          "type": "string"
        },
        "salary": {
          "type": "integer"
        }
      }
    }
  }
}

var descriptor = new CreateIndexDescriptor("myindex")
    .Mappings(ms => ms
        .Map<ParentWithStringId>(m => m
            .AutoMap()
        )
    );

var expected = new
{
    mappings = new
    {
        parent = new
        {
            properties = new
            {
                id = new
                {
                    type = "string",
                }
            }
        }
    }
};

var settings = WithConnectionSettings(s => s
    .InferMappingFor<ParentWithStringId>(m => m
        .TypeName("parent")
        .Ignore(p => p.Description)
        .Ignore(p => p.IgnoreMe)
    )
);

settings.Expect(expected).WhenSerializing((ICreateIndexRequest) descriptor);

Observe that NEST has inferred the Elasticsearch types based on the CLR type of our POCO properties. In this example,

and the remaining string properties as string datatypes.

NEST has inferred mapping support for the following .NET types

and supports a number of special types defined in NEST

All other types map to "object" by default.

If you notice in our previous Company and Employee example, the Employee type is recursive in that the Employee class itself contains a collection of type Employee. By default, .AutoMap() will only traverse a single depth when it encounters recursive instances like this; the collection of type Employee on the Employee class did not get any of its properties mapped.

This is done as a safe-guard to prevent stack overflows and all the fun that comes with infinite recursion. Additionally, in most cases, when it comes to Elasticsearch mappings, it is often an edge case to have deeply nested mappings like this. However, you may still have the need to do this, so you can control the recursion depth of .AutoMap().

Let’s introduce a very simple class, A, which itself has a property Child of type A.

public class A
{
    public A Child { get; set; }
}

By default, .AutoMap() only goes as far as depth 1

var descriptor = new CreateIndexDescriptor("myindex")
    .Mappings(ms => ms
        .Map<A>(m => m.AutoMap())
    );

Thus we do not map properties on the second occurrence of our Child property

{
  "mappings": {
    "a": {
      "properties": {
        "child": {
          "properties": {},
          "type": "object"
        }
      }
    }
  }
}

Now let’s specify a maxRecursion of 3

var withMaxRecursionDescriptor = new CreateIndexDescriptor("myindex")
    .Mappings(ms => ms
        .Map<A>(m => m.AutoMap(3))
    );

.AutoMap() has now mapped three levels of our Child property

{
  "mappings": {
    "a": {
      "properties": {
        "child": {
          "type": "object",
          "properties": {
            "child": {
              "type": "object",
              "properties": {
                "child": {
                  "type": "object",
                  "properties": {
                    "child": {
                      "type": "object",
                      "properties": {}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}