WARNING: Version 5.x has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

Elastic Docs ›Elasticsearch.Net and NEST: the .NET clients [2.x] ›Query DSL ›NEST specific queries
« Raw Query Usage Aggregations »

Verbatim and Strict Query Usageedit

NEST has the concept of conditionless queries; if the input to a query is determined to be empty, for example, null or "" for a string input, then the query will not be serialized and sent to Elasticsearch. If a conditionless query is part of a compound query then the query will not be part of the json query dsl sent to Elasticsearch.

Conditionless behavior can be controlled on individual queries by using Strict and Verbatim queries

Strict
Individual queries can be marked as strict meaning that if they are conditionless, an exception is thrown. This is useful for when a query must have an input value.
Verbatim
Individual queries can be marked as verbatim meaning that the query should be sent to Elasticsearch as is, even if it is conditionless.

Verbatim query usageedit

IsVerbatim should be set on individual queries to take effect

Fluent DSL exampleedit

q
.Bool(b => b
    .Must(qt => qt
        .Term(t => t
            .Verbatim()
            .Field(p => p.Description)
            .Value("")
        ), qt => qt
        .Term(t => t
            .Field(p => p.Name)
            .Value("foo")
        )
    )
)

Object Initializer syntax exampleedit

new TermQuery
{
    IsVerbatim = true,
    Field = "description",
    Value = ""
}
&& new TermQuery
{
    Field = "name",
    Value = "foo"
}

Example json output.

{
  "bool": {
    "must": [
      {
        "term": {
          "description": {
            "value": ""
          }
        }
      },
      {
        "term": {
          "name": {
            "value": "foo"
          }
        }
      }
    ]
  }
}

Non-Cascading Strict Outer Queriesedit

Setting IsStrict on the outer query container does not cascade

Fluent DSL exampleedit

q
.Strict()
.Bool(b => b
    .Must(qt => qt
        .Term(t => t
            .Field(p => p.Description)
            .Value("")
        ), qt => qt
        .Term(t => t
            .Field(p => p.Name)
            .Value("foo")
        )
    )
)

Object Initializer syntax exampleedit

IQueryContainer query = new QueryContainer(new BoolQuery
{
    Must = new List<QueryContainer>
    {
        new TermQuery
        {
            Field = "description",
            Value = ""
        },
        new TermQuery
        {
            Field = "name",
            Value = "foo"
        }
    }
});

query.IsStrict = true;
return (QueryContainer)query;

Example json output.

{
  "bool": {
    "must": [
      {
        "term": {
          "name": {
            "value": "foo"
          }
        }
      }
    ]
  }
}

Non-Cascading Verbatim Outer Queriesedit

Setting IsVerbatim on the outer query container does not cascade

Fluent DSL exampleedit

q
.Verbatim()
.Bool(b => b
    .Must(qt => qt
        .Term(t => t
            .Field(p => p.Description)
            .Value("")
        ), qt => qt
        .Term(t => t
            .Field(p => p.Name)
            .Value("foo")
        )
    )
)

Object Initializer syntax exampleedit

IQueryContainer query = new QueryContainer(new BoolQuery
{
    Must = new List<QueryContainer>
    {
        new TermQuery
        {
            Field = "description",
            Value = ""
        },
        new TermQuery
        {
            Field = "name",
            Value = "foo"
        }
    }
});

query.IsVerbatim = true;
return (QueryContainer)query;

Example json output.

{
  "bool": {
    "must": [
      {
        "term": {
          "name": {
            "value": "foo"
          }
        }
      }
    ]
  }
}

A compound query can also be marked as verbatim, demonstrated here with a bool query.

Fluent DSL exampleedit

q
.Bool(b => b
    .Verbatim()
)

Object Initializer syntax exampleedit

new BoolQuery
{
    IsVerbatim = true,
}

Example json output.

{
  "bool": {}
}

A single verbatim query will be serialized as-is

Fluent DSL exampleedit

q
.Term(t => t
    .Verbatim()
    .Field(p => p.Description)
    .Value("")
)

Object Initializer syntax exampleedit

new TermQuery
{
    IsVerbatim = true,
    Field = "description",
    Value = ""
}

Example json output.

{
  "term": {
    "description": {
      "value": ""
    }
  }
}

Leaf queries within a compound query marked as verbatim will also be serialized as-is

Fluent DSL exampleedit

q
.Bool(b => b
    .Filter(f => !f
        .Term(t => t
            .Verbatim()
            .Field(p => p.Name)
            .Value("")
        ) && f
        .Exists(e => e
            .Field(p => p.NumberOfCommits)
        )
    )
)

Object Initializer syntax exampleedit

new BoolQuery
{
    Filter = new QueryContainer[] {
        !new TermQuery
        {
            IsVerbatim = true,
            Field = "name",
            Value = ""
        } &&
        new ExistsQuery
        {
            Field = "numberOfCommits"
        }
    }
}

Example json output.

{
  "bool": {
    "filter": [
      {
        "bool": {
          "must": [
            {
              "exists": {
                "field": "numberOfCommits"
              }
            }
          ],
          "must_not": [
            {
              "term": {
                "name": {
                  "value": ""
                }
              }
            }
          ]
        }
      }
    ]
  }
}

Strict Query Usageedit

A query can be marked as strict meaning that if it is determined to be conditionless, it will throw an exception. The following example demonstrates this by trying to send an empty string as the value for a term query marked as strict

« Raw Query Usage Aggregations »