#510 document nrql dialect

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 * 2.4.next in progress
   * Address [#511](https://github.com/seancorfield/honeysql/issues/511) by adding support for BigQuery `CREATE OR REPLACE`.
-  * Address [#510](https://github.com/seancorfield/honeysql/issues/510) by adding some NRQL support (work-in-progress).
+  * Address [#510](https://github.com/seancorfield/honeysql/issues/510) by adding initial support for an NRQL dialect.
   * Fix [#509](https://github.com/seancorfield/honeysql/issues/509) by checking for `ident?` before checking keyword/symbol.
 
 * 2.4.1078 -- 2023-10-07

README.md

@@ -759,7 +759,7 @@ be quoted according to the selected dialect. If you override the dialect in a
 `format` call, by passing the `:dialect` option, SQL entity names will be automatically
 quoted. You can override the dialect and turn off quoting by passing `:quoted false`.
 Valid `:dialect` options are `:ansi` (the default, use this for PostgreSQL),
-`:mysql`, `:oracle`, or `:sqlserver`:
+`:mysql`, `:oracle`, or `:sqlserver`. As of 2.4.next, `:nrql` is also supported:
 
 ```clojure
 (-> (select :foo.a)
@@ -768,6 +768,15 @@ Valid `:dialect` options are `:ansi` (the default, use this for PostgreSQL),
     (sql/format {:dialect :mysql}))
 => ["SELECT `foo`.`a` FROM `foo` WHERE `foo`.`a` = ?" "baz"]
 ```
+```clojure
+(-> (select :foo.a)
+    (from :foo)
+    (where [:= :foo.a "baz"])
+    (sql/format {:dialect :nrql}))
+=> ["SELECT `foo.a` FROM `foo` WHERE `foo.a` = 'baz'"]
+```
+
+See [New Relic NRQL Support](nrsql.md) for more details of the NRQL dialect.
 
 #### Locking
 

build/honey/gen_doc_tests.clj

@@ -7,10 +7,12 @@
         success-marker (fs/file target "SUCCESS")
         docs ["README.md"
               "doc/clause-reference.md"
+              "doc/databases.md"
               "doc/differences-from-1-x.md"
               "doc/extending-honeysql.md"
               "doc/general-reference.md"
               "doc/getting-started.md"
+              "doc/nrql.md"
               ;;"doc/operator-reference.md"
               "doc/options.md"
               "doc/postgresql.md"

doc/cljdoc.edn

@@ -7,6 +7,7 @@
    ["SQL Operator Reference" {:file "doc/operator-reference.md"}]
    ["SQL 'Special Syntax'" {:file "doc/special-syntax.md"}]
    ["PostgreSQL Support" {:file "doc/postgresql.md"}]
+   ["New Relic NRQL Support" {:file "doc/nrql.md"}]
    ["Other Databases" {:file "doc/databases.md"}]]
   ["All the Options" {:file "doc/options.md"}]
   ["Extending HoneySQL" {:file "doc/extending-honeysql.md"}]

doc/databases.md

@@ -7,6 +7,7 @@ databases.
 As a reminder, HoneySQL supports the following dialects out of the box:
 * `:ansi` -- which is the default and provides broad support for PostgreSQL as well
 * `:mysql` -- which includes MariaDB and Percona
+* `:nrql` -- as of 2.4.next
 * `:oracle`
 * `:sqlserver` -- Microsoft SQL Server
 

doc/extending-honeysql.md

@@ -182,6 +182,7 @@ _New in HoneySQL 2.3.x_
 The built-in dialects that HoneySQL supports are:
 * `:ansi` -- the default, that quotes SQL entity names with double-quotes, like `"this"`
 * `:mysql` -- quotes SQL entity names with backticks, and changes the precedence of `SET` in `UPDATE`
+* `:nrql` -- as of 2.4.next, see [New Relic NRQL Support](nrsql.md) for more details of the NRQL dialect
 * `:oracle` -- quotes SQL entity names like `:ansi`, and does not use `AS` in aliases
 * `:sqlserver` -- quotes SQL entity names with brackets, like `[this]`
 

doc/getting-started.md

@@ -341,6 +341,7 @@ The dialects supported by HoneySQL 2.x are:
 * `:ansi` -- the default, including most PostgreSQL extensions
 * `:sqlserver` -- Microsoft SQL Server
 * `:mysql` -- MySQL (and Percona and MariaDB)
+* `:nrql` -- as of 2.4.next
 * `:oracle` -- Oracle
 
 The most visible difference between dialects is how SQL entities
@@ -355,6 +356,8 @@ Currently, the only dialect that has substantive differences from
 the others is `:mysql` for which the `:set` clause
 has a different precedence than ANSI SQL.
 
+See [New Relic NRQL Support](nrsql.md) for more details of the NRQL dialect.
+
 You can change the dialect globally using the `set-dialect!` function,
 passing in one of the keywords above. You need to call this function
 before you call `format` for the first time.

doc/nrql.md

@@ -0,0 +1,44 @@
+# New Relic NRQL Support
+
+As of 2.4.next, HoneySQL provides some support for New Relic's NRQL query language.
+
+At present, the following additional SQL clauses (and their corresponding
+helper functions) are supported:
+
+* `:facet` - implemented just like `:select`
+* `:since` - implemented like `:interval`
+* `:until` - implemented like `:interval`
+* `:compare-with` - implemented like `:interval`
+* `:timeseries` - implemented like `:interval`
+
+> Note: `:timeseries :auto` is the shortest way to specify a timeseries.
+
+When you select the `:nrql` dialect, SQL formatting assumes `:inline true`
+so that the generated SQL string can be used directly in NRQL queries.
+
+In addition, stropping (quoting) is done using backticks, like MySQL,
+but entities are not split at `/` or `.` characters, so that:
+
+```
+:foo/bar.baz ;;=> `foo/bar.baz`
+```
+
+```clojure
+user=> (require '[honey.sql :as sql])
+nil
+```
+```clojure
+user=> (sql/format {:select [:mulog/timestamp :mulog/event-name]
+                    :from   :Log
+                    :where  [:= :mulog/data.account "foo-account-id"]
+                    :since  [2 :days :ago]
+                    :limit 2000}
+                    {:dialect :nrql :pretty true})
+["
+SELECT `mulog/timestamp`, `mulog/event-name`
+FROM Log
+WHERE `mulog/data.account` = 'foo-account-id'
+LIMIT 2000
+SINCE 2 DAYS AGO
+"]
+```

src/honey/sql.cljc

@@ -2342,4 +2342,11 @@
                :since [1 :day :ago]
                :timeseries [:auto]}
               {:dialect :nrql})
+  (sql/format {:select [:mulog/timestamp :mulog/event-name]
+               :from   :Log
+               :where  [:= :mulog/data.account "foo-account-id"]
+               :since  [2 :days :ago]
+               :limit 2000}
+              {:dialect :nrql :pretty true})
+
   )