From 25883978def825562b426a7b8da974b8835491ab Mon Sep 17 00:00:00 2001
From: Zach Daniel <zach@zachdaniel.dev>
Date: Thu, 15 Jun 2023 20:54:37 -0400
Subject: [PATCH] improvement: add postgres expressions guide

---
 documentation/topics/postgres-expressions.md | 40 ++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 documentation/topics/postgres-expressions.md

diff --git a/documentation/topics/postgres-expressions.md b/documentation/topics/postgres-expressions.md
new file mode 100644
index 0000000..9bef39e
--- /dev/null
+++ b/documentation/topics/postgres-expressions.md
@@ -0,0 +1,40 @@
+# Postgres Expressions
+
+In addition to the expressions listed in the [Ash expressions guide](https://hexdocs.pm/ash/expressions.html), AshPostgres provides the following expressions
+
+## Fragments
+`fragment` allows you to embed raw sql into the query. Use question marks to interpolate values from the outer expression. 
+
+For example:
+
+```elixir
+Ash.Query.filter(User, fragment("? IS NOT NULL", first_name))
+```
+
+# Like and ILike
+
+These wrap the postgres builtin like and ilike operators. 
+
+Please be aware, these match *patterns* not raw text. Use `contains/1` if you want to match text without supporting patterns, i.e `%` and `_` have semantic meaning!
+
+For example:
+
+```elixir
+Ash.Query.filter(User, ilike(name, "%obo%")) # name contains obo anywhere in the string, case sensitively
+```
+
+```elixir
+Ash.Query.filter(User, ilike(name, "%ObO%")) # name contains ObO anywhere in the string, case insensitively
+```
+
+# Trigram similarity
+
+To use this expression, you must have the `pg_trgm` extension in your repos `installed_extensions` list.
+
+This calls the `similarity` function from that extension. See more https://www.postgresql.org/docs/current/pgtrgm.htmlhere: https://www.postgresql.org/docs/current/pgtrgm.html
+
+For example:
+
+```elixir
+Ash.Query.filter(User, trigram_similarity(first_name, "fred") > 0.8)
+```
\ No newline at end of file