diff --git a/docs/users-guide/images/SQL-filter-widget.png b/docs/users-guide/images/SQL-filter-widget.png deleted file mode 100644 index aac37bbd650852a0abd77d5cb9237c33ff0b78e9..0000000000000000000000000000000000000000 Binary files a/docs/users-guide/images/SQL-filter-widget.png and /dev/null differ diff --git a/docs/users-guide/images/SQLInterface.png b/docs/users-guide/images/SQLInterface.png deleted file mode 100644 index 67e200dbb070cbf063a29412b044f26e8f12b288..0000000000000000000000000000000000000000 Binary files a/docs/users-guide/images/SQLInterface.png and /dev/null differ diff --git a/docs/users-guide/images/writing-sql/SQL-filter-widget.png b/docs/users-guide/images/writing-sql/SQL-filter-widget.png new file mode 100644 index 0000000000000000000000000000000000000000..b655d826236df50465b4e20ece45c83558102258 Binary files /dev/null and b/docs/users-guide/images/writing-sql/SQL-filter-widget.png differ diff --git a/docs/users-guide/images/writing-sql/SQLInterface.png b/docs/users-guide/images/writing-sql/SQLInterface.png new file mode 100644 index 0000000000000000000000000000000000000000..006b430848b9b614acb30f3f03dcb8ea33c7feaf Binary files /dev/null and b/docs/users-guide/images/writing-sql/SQLInterface.png differ diff --git a/docs/users-guide/writing-sql.md b/docs/users-guide/writing-sql.md index 650c66bf6380658fece84eb84da8cf548dd70ce6..5edd54c029c9f3513e0bd4a1fcc3e2f5b969b754 100644 --- a/docs/users-guide/writing-sql.md +++ b/docs/users-guide/writing-sql.md @@ -1,34 +1,46 @@ # The SQL editor -If you ever need to ask questions that can't be expressed using the question builder, you can use **SQL** instead. +If you ever need to ask questions that can't be expressed using the query builder, you can use [SQL][sql-gloss] instead. ## What's SQL? -SQL (pronounced "sequel", or sometimes as S.Q.L.–people argue about this) stands for Structured Query Language, and is a widely used standard for getting data from databases. We won't try to teach you all about SQL in this guide, but to learn more about it, check out [Working with SQL][learn-sql]. +SQL (pronounced "sequel", or sometimes as S.Q.L. — people argue about this) stands for Structured Query Language, and is a widely used standard for getting data from databases. We won't try to teach you all about SQL right now, but to learn more about it, check out [Working with SQL][learn-sql]. -Even if you don't understand SQL or how to use it, it's worthwhile to understand how works inside Metabase because sometimes other people will share SQL-based questions that might be useful to you. +Even if you don't understand SQL or how to use it, it's worthwhile to get an idea of how it works inside Metabase, because sometimes other people will share SQL-based questions that might be useful to you. ## Starting a new SQL query -If you have the [permissions](../administration-guide/05-setting-permissions.md) to use the SQL editor, when you click the Ask a Question button you'll see an option to start a new SQL query. There's also a shortcut to the editor in the top nav bar; it's the little console icon. +Select **+ New** in the main nav bar. If you have the [permissions](../administration-guide/05-setting-permissions.md) to use the SQL editor, you'll see an option to start a new **SQL query** next to a little console icon. -You can write SQL (or your database's native querying language) directly into the editor that appears. +After clicking **SQL query**, you'll see an editor where you can write and run queries in SQL (or your database's native querying language). - + -To try it out, select the Sample Database, then type the command `select sum(subtotal), created_at from orders group by created_at`. Don't worry if you don't understand this just yet. Click the blue run button and note the table that comes back is the same as if you had asked for the sum of Subtotal in the Orders table, grouped by Created At. +To try it out, make sure you've selected the [Sample Database][sample-database-gloss], then paste in this short SQL query: -**Tip:** You can run your SQL query by pressing **ctrl + enter** on Windows and Linux, or **⌘ + return** on a Mac. You can also run only the selected section of a query by highlighting the part you'd like to run before clicking the run button or using the run shortcut key. +``` +SELECT + sum(subtotal), + created_at +FROM orders +GROUP BY created_at; +``` -Questions asked using SQL can be saved, downloaded, or added to a dashboard just like questions asked using the question builder. +Don't worry if you don't understand this just yet. Click the blue **Run query** button to execute your query. + +You'll notice that the table that comes back is the same as if you had used the [query builder][asking-questions] to ask for the sum of `Subtotal` in the `Orders` table, grouped by the `Created At` date. + +**Tip:** You can run your SQL query by pressing **ctrl + enter** on Windows and Linux, or **⌘ + return** on a Mac. You can also run only part of a query by highlighting the part you'd like to run before clicking the run button or using the run shortcut key. + +Questions asked using SQL can be saved, downloaded, converted to models, and added to dashboards just like questions asked using the query builder. You can also [refer to models and saved questions][ref-models] in your SQL queries. ## Using SQL filters -If you or someone else wrote a SQL query that includes [variables](13-sql-parameters.md), your question might have filter widgets at the top of the screen. Filter widgets let you modify the SQL query before it's run, changing the results you might get. +If you or someone else wrote a SQL query that includes [variables][variable-gloss], that question might have filter widgets at the top of the screen above the editor. Filter widgets let you modify the SQL query before it's run, changing the results you might get. - + Writing SQL queries that use variables or parameters can be very powerful, but it's also a bit more advanced, so that topic has its own page if you'd like to [learn more](13-sql-parameters.md). @@ -46,5 +58,9 @@ You can use [SQL snippets](sql-snippets.md) to save, reuse, and share SQL code a Now that you have an answer to your question, you can learn about [visualizing answers](05-visualizing-results.md). +[asking-questions]: ../users-guide/04-asking-questions.html#creating-a-new-question-with-the-query-builder [learn-sql]: https://www.metabase.com/learn/sql-questions [ref-models]: ./referencing-saved-questions-in-queries.md +[sample-database-gloss]: /glossary/sample_database +[sql-gloss]: /glossary/sql +[variable-gloss]: /glossary/variable