Tell a bit more about SQL name resolution.

set-database.md

@@ -6,7 +6,7 @@ toc: false
 
 The `SET DATABASE` [statement](sql-statements.html) sets the default database for the current session. When connected to the default database, you don't need to reference it explicitly in statements.
 
-{{site.data.alerts.callout_danger}}In some cases, client drivers can drop and restart the connection to the server. When this happens, any session configurations made with <code>SET</code> statements are lost. It's therefore more reliable to set the database in the client's connection string. For examples in different languages, see <a href="build-a-test-app.html">Build a Test App</a>.{{site.data.alerts.end}}
+{{site.data.alerts.callout_danger}}In some cases, client drivers can drop and restart the connection to the server. When this happens, any session configurations made with <code>SET</code> statements are lost. It is therefore more reliable to set the database in the client's connection string. For examples in different languages, see <a href="build-a-test-app.html">Build a Test App</a>.{{site.data.alerts.end}}
 
 <div id="toc"></div>
 
@@ -90,6 +90,7 @@ $ cockroach sql --database=db1
 
 ## See Also
 
+- [Name resolution rules for function and table names](sql-name-resolution.html)
 - [`SET TIME ZONE`](set-time-zone.html)
 - [`SET TRANSACTION`](set-transaction.html)
- 
+

sql-expressions.md

@@ -27,14 +27,21 @@ They are described further in section [SQL Constants](sql-constants.html).
 
 An expression in a query can refer to columns in the current data source in two ways:
 
-- Using the name of the column, e.g. "`price`" in `SELECT price FROM
-  items`. If the name of a column is also a
-  [SQL keyword](keywords-and-identifiers.html#keywords), the name must
-  be appropriately quoted. For example: `SELECT "Default" FROM
-  configuration`.
+- Using the name of the column, e.g., `price` in `SELECT price FROM
+  items`.
 
-- Using the ordinal position of the column. For example, `SELECT @1 FROM items` selects
-  the first column in `items`.
+  - If the name of a column is also a
+	[SQL keyword](keywords-and-identifiers.html#keywords), the name
+	must be appropriately quoted. For example: `SELECT "Default" FROM
+	configuration`.
+
+  - If the name is ambiguous (e.g., when joining across multiple
+	tables), it is possible to disambiguate by prefixing the column
+	name by the table name. For example, `SELECT items.price FROM
+	items`.
+
+- Using the ordinal position of the column. For example, `SELECT @1
+  FROM items` selects the first column in `items`.
 
   *This is a CockroachDB SQL extension.*
 
@@ -273,8 +280,12 @@ A built-in function name followed by an opening parenthesis, followed
 by a comma-separated list of expressions, followed by a closing
 parenthesis.
 
-This applies the named function to the arguments between the parentheses.
-See [the separate section on supported built-in functions](functions-and-operators.html).
+This applies the named function to the arguments between
+parentheses. When the function's namespace is not prefixed, the
+[name resolution rules](sql-name-resolution.html) determine which
+function is called.
+
+See also [the separate section on supported built-in functions](functions-and-operators.html).
 
 In addition, the following SQL special forms are also supported:
 
@@ -359,7 +370,7 @@ Syntax:
 
 ~~~
 CASE <cond>
-    WHEN <condval1> THEN <expr1>
+	WHEN <condval1> THEN <expr1>
   [ WHEN <condvalx> THEN <exprx> ] ...
   [ ELSE <expr2> ]
 END

sql-name-resolution.md

@@ -0,0 +1,50 @@
+---
+title: Name Resolution
+summary: Table and function names can exist in multiple places. Resolution decides which one to use.
+toc: false
+---
+
+A SQL client can have access to multiple databases side-by-side. The
+same table name (e.g., `orders`) can exist in multiple
+databases. When a query specifies a table name without a database
+name (e.g., `select * from orders`), how does CockroachDB know
+which `orders` table is being considered?
+
+This page details how CockroachDB performs *name resolution* to answer
+this question.
+
+<div id="toc"></div>
+
+## Overview
+
+The following *name resolution algorithm* is used both to determine
+table names in [table expressions](table-expressions.html) and
+function names in [value expressions](sql-expressions.html):
+
+- If the name is *qualified* (i.e., the name already tells where to look), use this information.
+  For example, `SELECT * FROM db1.orders` will look up "`orders`" only in `db1`.
+- If the name is *unqualified*:
+  - Try to find the name in the "default database" as set by [`SET DATABASE`](set-database.html).
+  - Try to find the name using the [search path](#search-path).
+  - If the name is not found, produce an error.
+
+## Search path
+
+In addition to the default database configurable via [`SET DATABASE`](set-database.html),
+unqualified names are also looked up in the current session's *search path*.
+
+The search path is a session variable containing a list of databases,
+or *name spaces*, where names are looked up.
+
+The current search path can be inspected using the statement `SHOW
+SEARCH_PATH`, or [`SHOW ALL`](show-all.html).
+
+By default, the search path for new columns includes just
+`pg_catalog`, so that queries can use PostgreSQL compatibility
+functions and virtual tables in that namespace without the need to
+prefix them with "`pg_catalog.`" every time.
+
+## See also
+
+- [List of predefined databases](predefined-namespaces.html)
+- [`SET DATABASE`](set-database.html)

table-expressions.md

@@ -48,8 +48,9 @@ A single SQL identifier in a table expression context designates
 the contents of the table or [view](views.html) with that name
 in the current database, as configured by [`SET DATABASE`](set-database.html).
 
-If the name is prefixed by another identifier and a period, the table or view
-is searched in the database with that name.
+If the name is prefixed by another identifier and a period, the table
+or view is searched in the database with that name. See the section on
+[name resolution](sql-name-resolution.html) for more details.
 
 For example: