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

@@ -33,6 +33,11 @@ An expression in a query can refer to columns in the current data source in two
   be appropriately quoted. For example: `SELECT "Default" FROM
   configuration`.
 
+  In case the column 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`.
 
@@ -274,7 +279,10 @@ 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).
+
+Which function is called depending on the name used is determined using
+the regular [name resolution](sql-name-resolution.html) rules.
+See also [the separate section on supported built-in functions](functions-and-operators.html).
 
 In addition, the following SQL special forms are also supported:
 

sql-name-resolution.md

@@ -0,0 +1,44 @@
+---
+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, for example, `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 given name already tells where to look explicitly, i.e. it is *qualified*, then just use this information.
+- Otherwise, i.e. 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 was not found so far, 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`.
+
+Every new session has a search path initialized to a single item:
+`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.

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: