From 1b0d681cff3f3a20500a1d7614b820dd3f78f819 Mon Sep 17 00:00:00 2001 From: Raphael 'kena' Poss Date: Tue, 31 Jan 2017 16:05:09 +0000 Subject: [PATCH] Tell a bit more about SQL name resolution. --- set-database.md | 5 +++-- sql-expressions.md | 31 +++++++++++++++++--------- sql-name-resolution.md | 50 ++++++++++++++++++++++++++++++++++++++++++ table-expressions.md | 5 +++-- 4 files changed, 77 insertions(+), 14 deletions(-) create mode 100644 sql-name-resolution.md diff --git a/set-database.md b/set-database.md index d9f74d95230..064da081f4a 100644 --- a/set-database.md +++ b/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 SET statements are lost. It's therefore more reliable to set the database in the client's connection string. For examples in different languages, see Build a Test App.{{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 SET statements are lost. It is therefore more reliable to set the database in the client's connection string. For examples in different languages, see Build a Test App.{{site.data.alerts.end}}
@@ -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) - \ No newline at end of file + diff --git a/sql-expressions.md b/sql-expressions.md index 2101558b714..2ad6f5e52e7 100644 --- a/sql-expressions.md +++ b/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 - WHEN THEN + WHEN THEN [ WHEN THEN ] ... [ ELSE ] END diff --git a/sql-name-resolution.md b/sql-name-resolution.md new file mode 100644 index 00000000000..ad0003725df --- /dev/null +++ b/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. + +
+ +## 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) diff --git a/table-expressions.md b/table-expressions.md index d80d8b4e2e1..03434a05303 100644 --- a/table-expressions.md +++ b/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: