Clean up Native Query Analyzer documentation (#41830)

Also add the replace-names fn, which is a simple pass-through to Macaw #modularity

src/metabase/models/query_field.clj

@@ -3,7 +3,6 @@
    [methodical.core :as methodical]
    [toucan2.core :as t2]))
 
-
 (methodical/defmethod t2/table-name :model/QueryField [_model] :query_field)
 
 (doto :model/QueryField

src/metabase/native_query_analyzer.clj

@@ -3,7 +3,12 @@
   namespace is to:
 
   1. Translate Metabase-isms into generic SQL that Macaw can understand.
-  2. Contain Metabase-specific business logic."
+  2. Contain Metabase-specific business logic.
+
+  The primary way of interacting with parsed queries is through their associated QueryFields (see model
+  file). QueryFields are maintained through the `update-query-fields-for-card!` function.
+
+  Query rewriting happens with the `replace-names` function."
   (:require
    [clojure.set :as set]
    [clojure.string :as str]
@@ -136,3 +141,15 @@
           (t2/insert! :model/QueryField query-field-records)))
       (catch Exception e
         (log/error e "Error parsing native query")))))
+
+;; TODO: does not support template tags
+(defn replace-names
+  "Returns a modified query with the given table and column renames applied. `renames` is expected to be a map with
+  `:tables` and `:columns` keys, and values of the shape `old-name -> new-name`:
+
+  (replace-names \"SELECT o.id, o.total FROM orders o\" {:columns {\"id\" \"pk\"
+                                                                   \"total\" \"amount\"}
+                                                         :tables {\"orders\" \"purchases\"}})
+ ;; => \"SELECT o.pk, o.amount FROM purchases o\""
+  [sql-query renames]
+  (macaw/replace-names sql-query renames))