document Differences between IN queries between v1 and v2 #418

doc/operator-reference.md

@@ -32,6 +32,47 @@ can simply evaluate to `nil` instead).
 ;;=> ["...WHERE (id = ?) OR (type = ?)..." 42 "match"]
 ```
 
+## in
+
+Binary predicate for checking an expression is
+is a member of a specified set of values.
+
+The two most common forms are:
+
+* `[:in :col [val1 val2 ...]]` where the `valN` can be arbitrary expressions,
+* `[:in :col {:select ...}]` where the `SELECT` specifies a single column.
+
+`:col` could be an arbitrary SQL expression (but is most
+commonly just a column name).
+
+The former produces an inline vector expression with the
+values resolved as regular SQL expressions (i.e., with
+literal values lifted out as parameters): `col IN [?, ?, ...]`
+
+The latter produces a sub-select, as expected: `col IN (SELECT ...)`
+
+You can also specify the set of values via a named parameter:
+
+* `[:in :col :?values]` where `:params {:values [1 2 ...]}` is provided to `format` in the options.
+
+In this case, the named parameter is expanded directly when
+`:in` is formatted to obtain the sequence of values (which
+must be _sequential_, not a Clojure set). That means you
+cannot use this approach and also specify `:cache` -- see
+[cache in All the Options](options.md#cache) for more details.
+
+Another supported form is checking whether a tuple is in
+a selected set of values that specifies a matching number
+of columns, producing `(col1, col2) IN (SELECT ...)`, but
+you need to specify the columns (or expressions) using the
+`:composite` special syntax:
+
+* `[:in [:composite :col1 :col2] ...]`
+
+This produces `(col1, col2) IN ...`
+
+> Note: This is a change from HoneySQL 1.x which accepted a sequence of column names but required more work for arbitrary expressions.
+
 ## = <> < > <= >=
 
 Binary comparison operators. These expect exactly