diff --git a/docs/en/sql-reference/00-sql-reference/41-sql-variables.md b/docs/en/sql-reference/00-sql-reference/41-sql-variables.md deleted file mode 100644 index cb361ec997..0000000000 --- a/docs/en/sql-reference/00-sql-reference/41-sql-variables.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: SQL Variables -sidebar_label: SQL Variables ---- - -SQL variables allow you to store and manage temporary data within a session. - -## Variable DDL Commands - -Databend provides the following DDL commands for using SQL variables: - -- [SET VARIABLE](../10-sql-commands/00-ddl/15-variable/set-variable.md) -- [SHOW VARIABLES](../10-sql-commands/00-ddl/15-variable/show-variables.md) -- [UNSET VARIABLE](../10-sql-commands/00-ddl/15-variable/unset-variable.md) - -The SHOW VARIABLES command has a corresponding table function, [SHOW_VARIABLES](../20-sql-functions/17-table-functions/show-variables.md), which provides the same information in a table format, allowing for more complex filtering and querying within SQL statements. - -## Querying with Variables - -This section explains how to effectively use variables in your queries, leveraging both `$` for value substitution and `IDENTIFIER` for accessing database objects like tables. - -### Accessing Variables with `$` and `getvariable()` - -You can reference the value of a variable within a SQL statement using either the `$` symbol or the `getvariable()` function. Both methods allow dynamic substitution, where the variable's value is directly embedded into the query at runtime. - -```sql title='Example:' --- Set a variable to use as a filter value -SET VARIABLE threshold = 100; - --- Use the variable in a query with $ -SELECT * FROM sales WHERE amount > $threshold; - --- Alternatively, use the getvariable() function -SELECT * FROM sales WHERE amount > getvariable('threshold'); -``` - -### Accessing Objects with `IDENTIFIER` - -The `IDENTIFIER` keyword allows you to dynamically reference database objects whose names are stored in variables. Please note that accessing objects with `IDENTIFIER` is *not* supported by BendSQL yet. - -```sql title='Example:' --- Create a table with sales data -CREATE TABLE sales_data (region TEXT, sales_amount INT, month TEXT) AS -SELECT 'North', 5000, 'January' UNION ALL -SELECT 'South', 3000, 'January'; - -select * from sales_data; - --- Set variables for the table name and column name -SET VARIABLE table_name = 'sales_data'; -SET VARIABLE column_name = 'sales_amount'; - --- Use IDENTIFIER to dynamically reference the table and column in the query -SELECT region, IDENTIFIER($column_name) -FROM IDENTIFIER($table_name) -WHERE IDENTIFIER($column_name) > 4000; -``` \ No newline at end of file diff --git a/docs/en/sql-reference/10-sql-commands/00-ddl/15-variable/index.md b/docs/en/sql-reference/10-sql-commands/00-ddl/15-variable/index.md index 04f5f4ecae..ac5fdfc0c1 100644 --- a/docs/en/sql-reference/10-sql-commands/00-ddl/15-variable/index.md +++ b/docs/en/sql-reference/10-sql-commands/00-ddl/15-variable/index.md @@ -1,22 +1,57 @@ --- -title: Variable +title: SQL Variables +sidebar_label: SQL Variables --- -This page provides a comprehensive overview of Variable operations in Databend, organized by functionality for easy reference. +SQL variables allow you to store and manage temporary data within a session, making scripts more dynamic and reusable. -## Variable Management +## Variable Commands | Command | Description | |---------|-------------| -| [SET](set-variable.md) | Creates or modifies a session or user variable | -| [UNSET](unset-variable.md) | Removes a user-defined variable | +| [SET VARIABLE](set-variable.md) | Creates or modifies a session or user variable. | +| [UNSET VARIABLE](unset-variable.md) | Removes a user-defined variable. | +| [SHOW VARIABLES](show-variables.md) | Displays current values of system and user variables. | -## Variable Information +The SHOW VARIABLES command also has a table function counterpart, [`SHOW_VARIABLES`](../../../20-sql-functions/17-table-functions/show-variables.md), which returns the same information in a tabular format for richer filtering and querying. -| Command | Description | -|---------|-------------| -| [SHOW VARIABLES](show-variables.md) | Displays current values of system and user variables | +## Querying with Variables + +You can reference variables in statements for dynamic value substitution or to build object names at runtime. + +### Accessing Variables with `$` and `getvariable()` + +Use the `$` symbol or the `getvariable()` function to embed variable values directly in a query. + +```sql title='Example:' +-- Set a variable to use as a filter value +SET VARIABLE threshold = 100; + +-- Use the variable in a query with $ +SELECT * FROM sales WHERE amount > $threshold; + +-- Alternatively, use the getvariable() function +SELECT * FROM sales WHERE amount > getvariable('threshold'); +``` + +### Accessing Objects with `IDENTIFIER` + +The `IDENTIFIER` keyword lets you reference database objects whose names are stored in variables, enabling flexible query construction. (Note: BendSQL does not yet support `IDENTIFIER`.) + +```sql title='Example:' +-- Create a table with sales data +CREATE TABLE sales_data (region TEXT, sales_amount INT, month TEXT) AS +SELECT 'North', 5000, 'January' UNION ALL +SELECT 'South', 3000, 'January'; + +select * from sales_data; + +-- Set variables for the table name and column name +SET VARIABLE table_name = 'sales_data'; +SET VARIABLE column_name = 'sales_amount'; -:::note -Variables in Databend allow you to store and reuse values within a session or across sessions, making scripts more dynamic and reusable. -::: \ No newline at end of file +-- Use IDENTIFIER to dynamically reference the table and column in the query +SELECT region, IDENTIFIER($column_name) +FROM IDENTIFIER($table_name) +WHERE IDENTIFIER($column_name) > 4000; +``` diff --git a/site-redirects.ts b/site-redirects.ts index cd342023e5..743c994492 100644 --- a/site-redirects.ts +++ b/site-redirects.ts @@ -19,6 +19,10 @@ const siteRedirects = [ from: '/guides/access-data-lake/delta', to: '/sql/sql-reference/table-engines/delta' }, + { + from: '/sql/sql-reference/sql-variables', + to: '/sql/sql-commands/ddl/variable/' + }, // AI Functions redirects - functions moved to external implementation { from: '/sql/sql-functions/ai-functions/ai-cosine-distance',