diff --git a/CHANGELOG.md b/CHANGELOG.md index ea5ebf6..7541716 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index f3ef552..574b63d 100644 --- a/README.md +++ b/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 diff --git a/build/honey/gen_doc_tests.clj b/build/honey/gen_doc_tests.clj index 22e8748..a2fd328 100644 --- a/build/honey/gen_doc_tests.clj +++ b/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" diff --git a/doc/cljdoc.edn b/doc/cljdoc.edn index 03594f5..311e99f 100644 --- a/doc/cljdoc.edn +++ b/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"}] diff --git a/doc/databases.md b/doc/databases.md index 01c2b3c..e729849 100644 --- a/doc/databases.md +++ b/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 diff --git a/doc/extending-honeysql.md b/doc/extending-honeysql.md index 5c8fe0b..c5f6a60 100644 --- a/doc/extending-honeysql.md +++ b/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]` diff --git a/doc/getting-started.md b/doc/getting-started.md index 67b930c..a5e158e 100644 --- a/doc/getting-started.md +++ b/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. diff --git a/doc/nrql.md b/doc/nrql.md new file mode 100644 index 0000000..b6d8563 --- /dev/null +++ b/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 +"] +``` diff --git a/src/honey/sql.cljc b/src/honey/sql.cljc index 1e49f88..9e7365a 100644 --- a/src/honey/sql.cljc +++ b/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}) + )