ElasticGraph Query API: Full Text Search

Try these example queries by visiting the GraphiQL UI after booting locally.

$ curl -s https://block.github.io/elasticgraph/dc.yml | docker compose -f - up --pull always

ElasticGraph supports three full-text search filtering predicates:

matchesPhrase: Matches records where the field value has a phrase matching the provided phrase using full text search. This is stricter than matchesQuery: all terms must match and be in the same order as the provided phrase.
When null is passed, matches all documents.
matchesQuery: Matches records where the field value matches the provided query using full text search. This is more lenient than matchesPhrase: the order of terms is ignored, and, by default, only one search term is required to be in the field value.
When null is passed, matches all documents.
matchesQueryWithPrefix: Matches records where the field value matches the provided query terms with prefix matching using full text search. Similar to matchesQuery but allows prefix matching on the last term in the query.
When null is passed, matches all documents.

Matches Query

matchesQuery is the more lenient of the two predicates. It’s designed to match broadly. Here’s an example:

query AccordionOrViolinSearch {
  artists(filter: {
    bio: {
      description: {
        matchesQuery: {
          query: "accordion violin"
        }
      }
    }
  }) {
    nodes {
      name
      bio {
        description
      }
    }
  }
}

This query will match artists with bios like:

Renowned for his mesmerizing performances, Luca “The Breeze” Fontana captivates audiences with his accordion, weaving intricate melodies that dance between the notes of traditional folk and modern jazz.

Sylvia Varela’s avant-garde violin playing defies tradition, blending haunting dissonance with unexpected rhythms.

Notably, the description needs accordion OR violin, but not both. In addition, it would match an artist bio that mentioned “viola” since it supports fuzzy matching by default and “viola” is only 2 edits away from “violin”. Arguments are supported to control both aspects to make matching stricter:

query AccordionAndViolinStrictSearch {
  artists(filter: {
    bio: {
      description:{
        matchesQuery: {
          query: "accordion violin"
          requireAllTerms: true
          allowedEditsPerTerm: NONE
        }
      }
    }
  }) {
    nodes {
      name
      bio {
        description
      }
    }
  }
}

Matches Phrase

matchesPhrase is even stricter: it requires all terms in the provided order (matchesQuery doesn’t care about order). It’s particularly useful when you want to search on a particular multi-word expression:

query PhraseSearch {
  artists(filter: {
    bio: {
      description:{
        matchesPhrase: {
          phrase: "unique musical identity"
        }
      }
    }
  }) {
    nodes {
      name
      bio {
        description
      }
    }
  }
}

Matches Query With Prefix

matchesQueryWithPrefix is similar to matchesQuery but additionally supports prefix matching on the last term of the query. This is especially useful when you want to implement search-as-you-type functionality:

query MatchesSearchWithPrefix {
  artists(filter: {
    bio: {
      description:{
        matchesQueryWithPrefix: {
          queryWithPrefix: "accordion vi"
          requireAllTerms: true
          allowedEditsPerTerm: NONE
        }
      }
    }
  }) {
    nodes {
      name
      bio {
        description
      }
    }
  }
}

This query will match artists with bios like:

Marco Romano is renowned for his masterful accordion performances accompanied by violin, creating a fusion of traditional and contemporary sounds.

The ensemble features virtuoso accordion players, producing a distinctive chamber music experience.

Notice that it matches “violin” and “virtuoso” even though the query is for “vi” (prefix match), and because requireAllTerms: true is specified, the bio must also contain “accordion”. By setting allowedEditsPerTerm: NONE, we’re ensuring exact matching for the terms (except for the prefix behavior on the last term).

Bypassing matchesPhrase, matchesQuery, and matchesQueryWithPrefix

In order to make a matchesPhrase, matchesQuery, or matchesQueryWithPrefix filter optional, you can supply null to the filter input parameter, like this:

query OptionalMatchingFilter(
  $optionalMatchQuery: MatchesQueryFilterInput = null
) {
  artists(filter: {
    bio: {
      description: {
        matchesQuery: $optionalMatchQuery
      }
    }
  }) {
    nodes {
      name
      bio {
        description
      }
    }
  }
}