dk.simongray.drop-in-search.queries — dk.simongray/drop-in-search 0.1.0

The query language of full-text search, and a query matched against one text without an index, on both platforms.

The comments name the source of each part, and where it departs from it:

• Lucene's simple query parser and FuzzyQuery, https://lucene.apache.org/core/9_11_1/core/
• Elasticsearch's simple_query_string, https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-simple-query-string-query
• SQLite FTS5's query syntax and its snippet function, https://www.sqlite.org/fts5.html

default-limits clj/s

The limits that keep the cost of a query that anyone can type within bounds, when its options don't set them:

• :max-terms, the words and phrases of a query that count, the first
• :max-depth, the groups in groups of a query, where a deeper one is read without its parentheses

matches? clj/s

(matches? text q)

(matches? text q opts)

Whether text matches the query q, read with the opts of snippet, as one field of a document would.

parse clj/s

(parse q)

(parse q opts)

The query q, a string, as data, read with the opts below, or nil when it asks for nothing.

Words must all occur, and the last word is a prefix to complete when nothing follows it, not even a space, unless it's in quotes. The operators are AND or &, OR or |, and NOT, or ! or - before a word, with parentheses, "a phrase", a prefix*, a word with typos~ and field:word or field=word for a word in one field:

(parse "title:clojure -rust" {:aliases {"title" :title}})
;; => {:and [{:term "clojure" :field :title}
;;           {:not {:term "rust" :prefix? true}}]}

A query as data is a map of :and or :or with a vector of queries, of :not with a query, of :term with a term, or of :phrase with a vector of terms in a row. A term or phrase has :prefix? when its last term is a prefix, and :field when it's in that field only. A term has :fuzzy, :auto or a number of edits, when it allows typos.

The opts are:

• :aliases, the names that a query can give fields, as a map of a name to a field
• :syntax, the spellings of operators over the defaults, e.g. OG for AND in Danish with {:and #{"OG" "&"}}
• :operator, :and or :or between words without one, :and by default
• :prefix?, false to take the last word whole
• :min-prefix, the fewest characters of a last word to complete, 1 by default
• :max-terms, the most words and phrases that count, and :max-depth, the deepest that groups nest

Nothing is an error, and a sign or a parenthesis that makes no sense counts for nothing.

snippet clj/s

(snippet text q)

(snippet text q {:keys [width] :or {width 160} :as opts})

A window of text around the words that match the query q, as parts to render, with the opts below.

It's a vector of maps of :text, with :match? on the matches, and an ellipsis where the window cuts the text. The text is plain, so escape it to put it into HTML. The window holds the most of the query's words and phrases, as in SQLite FTS5. The query is a string, the same query as data, or a vector of terms taken as they are. The opts are those of parse, and these:

• :width, the number of characters shown, 160 by default
• :fuzzy, which words match words with typos too: by default those that :known-pred doesn't know, true for all, a number for all with at most that many edits, up to 2, and false for none but those marked with ~
• :typo-lengths, the shortest words with one edit and with two, [3 6] by default, as Elasticsearch's AUTO
• :known-pred, a predicate of a term of a query, e.g. {:term "clojure"}, that tells whether the documents of an index hold it; without it, no word is unknown

syntax clj/s

The spellings of the operators of the query language.

A spelling of letters, e.g. AND, is an operator only as a word of its own, and a sign, e.g. &, inside a word too. A sign of :not counts only at the start of a word, and one of :field only after the name of a field. One of :prefix counts only at the end of a word, and so does one of :fuzzy, which a number of edits can follow, e.g. clojre~1.