What's the right way to perform a keyword search?

If I want to perform a keyword search using a TermQuery, what's the proper way to do this? Am I supposed to prepend ".keyword" to my field name? I would think there is a more first-class citizen way of doing it! 🤷‍♂️

QueryBuilders.termQuery(SOME_FIELD_NAME + ".keyword", someValue)

It all boils down to your mapping. If your field is mapped as a 'straightforward' keyword like so

{
  "mappings": {
    "properties": {
      "some_field": {
        "type": "keyword"
      }
    }
  }
}

you won't need to append .keyword -- you'd do just

QueryBuilders.termQuery(SOME_FIELD_NAME, someValue)

It's good practice, though, not to restrict yourself to only keywords, esp. if you'll be doing partial matches, expansions, autocomplete etc down the line.

A typical text field mapping would look like

PUT kwds
{
  "mappings": {
    "properties": {
      "some_field": {
        "type": "text",
        "fields": {
          "keyword": {          <---
            "type": "keyword"
          },
          "analyzed": {         <---
            "type": "text",
            "analyzer": "simple"
          },
          "...": {              <---
             ...
          }
        }
      }
    }
  }
}

This means you'd be able to access differently-indexed "versions" (fields) of the same "property" (field). The naming is rather confusing but you get the gist.

Long story short, this is where the .keyword convention stems from. You don't need it if your field is already mapped as a keyword.