{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n", "\n", "## SQL Notebooks in Azure Data Studio\n", "\n", "Notebooks allow rich text, images, code, and resultsets to be easily shared. This is a concept that is widely used in data science and which we feel is well suited to SQL work. \n" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "select \n", " 'Hello SQL World' as [Greetings], \n", " @@servername as [Server Name],\n", " datename(weekday,getutcdate()) as [Today]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Concepts\n", "\n", "Notebooks are saved in a file format of .ipynb and have a couple of logical components.\n", "\n", "**Kernel**\n", "\n", "The language and execution environment of the notebook. Common examples are Python and PowerShell. Azure Data Studio also offers a SQL kernel, which is the focus of this tutorial.\n", "\n", "**Attach To**\n", "\n", "This is the compute environment for the code - basically, where it will run. For SQL this is exactly analogous to the familiar Connection property of a query.\n", "\n", "**Cell**\n", "\n", "A cell is an editable section of the notebook. Cells can be human-readable text or code. Text cells are edited in the Markdown language to allow formatting and can include rich content including images. In Azure Data Studio, code cells include intellisense where possible. Below is an example of a SQL code cell.\n" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/html": [ "(5 rows affected)" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "Total execution time: 00:00:00.163" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "application/vnd.dataresource+json": { "data": [ { "0": "59", "1": "ASYNC_NETWORK_IO", "2": "24", "3": "389", "4": "347", "5": "0" }, { "0": "57", "1": "PREEMPTIVE_XE_GETTARGETSTATE", "2": "9", "3": "160", "4": "102", "5": "0" }, { "0": "57", "1": "ASYNC_NETWORK_IO", "2": "323", "3": "38", "4": "2", "5": "10" }, { "0": "58", "1": "MEMORY_ALLOCATION_EXT", "2": "5066", "3": "25", "4": "0", "5": "0" }, { "0": "60", "1": "PAGEIOLATCH_SH", "2": "30", "3": "11", "4": "0", "5": "0" } ], "schema": { "fields": [ { "name": "session_id" }, { "name": "wait_type" }, { "name": "waiting_tasks_count" }, { "name": "wait_time_ms" }, { "name": "max_wait_time_ms" }, { "name": "signal_wait_time_ms" } ] } }, "text/html": [ "
session_idwait_typewaiting_tasks_countwait_time_msmax_wait_time_mssignal_wait_time_ms
59ASYNC_NETWORK_IO243893470
57PREEMPTIVE_XE_GETTARGETSTATE91601020
57ASYNC_NETWORK_IO32338210
58MEMORY_ALLOCATION_EXT50662500
60PAGEIOLATCH_SH301100
" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "select top 5 * from sys.dm_exec_session_wait_stats order by wait_time_ms desc" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**Results**\n", "\n", "Code cells can be executed against the environment specified in Attach To, and their results are saved into the notebook. Once executed and saved, the results can be opened with the file without having be be re-executed. Results may be text, grids, charts, or other visualizations.\n", "\n", "**Trusted vs Non-Trusted**\n", "\n", "Since notebooks can contain HTML and Javascript code, it would be possible for a maliciously formed notebook to execute code simply upon being opened by the user. To prevent this, notebooks have the concept of \"Trusted\" and \"Untrusted.\" Untrusted HTML is sanitized and untrusted Javascript is not executed. Users can mark notebooks trusted if necessary, but in common use cases an untrusted notebook will perform the same as a trusted one. This is similar to the behavior of many other file types when downloaded from the internet." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Editing Experience\n", "\n", "Editing SQL is the same in Azure Data Studio notebooks as in the Azure Data Studio query editor - the same Intellisense, the same snippet support. Markdown is edited with a custom editor which shows a preview during edit, and only shows the processed markdown when not in edit mode. Code and markdown (text) cells can be added with buttons or through context menus." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "select top 10 * from sys.databases" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Code Separation and Context\n", "\n", "The separate code cells in a SQL notebook are run as separate batches. This is equivalent to having a GO statement between cells.\n", "\n", "This is an area we're actively innovating in and want to make a little more straightforward! But we'll describe the current behavior.\n", "\n", "In this code, we're setting the database context to WideWorldImporters and then creating a local variable. We're also setting nocount on, to demonstrate set statement behavior." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "set nocount on;\n", "use WideWorldImporters;\n", "declare @i int;\n", "set @i = 1;\n", "select @i [Value of @i], db_name() as [MyDatabaseName]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The next cell will show an error, since the variable @i is not declared within this cell." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "select @i [Value of @i], db_name() as [MyDatabaseName]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In the next cell, we're re-declaring @i, but not setting it, so the value remains null.\n", "\n", "However, the previously set database context and nocount settings are maintained as these are durable throughout the session. This is the same behavior as the query editor." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "declare @i int;\n", "select @i [Value of @i], db_name() as [MyDatabaseName]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "One upshot of this - not unique to SQL notebooks - is that code cell execution order *does matter*\n", "\n", "We think this is an area we can innovate in and welcome your suggestions on how to make this easier to work with in a notebook context." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Multi-language support\n", "\n", "While in a SQL notebook you can change to run R and Python on the SQL Server with a special syntax. This allows you to type your raw Python or R and execute it without having to remember how to wrap it up in a stored procedure (provided that the Advanced Analytics Extensions feature is installed and enabled on the target server)" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "language": "python" }, "outputs": [ { "data": { "text/html": [ "STDOUT message(s) from external script: \n", "Hello World\r" ] }, "metadata": {}, "output_type": "display_data" }, { "data": { "text/html": [ "Total execution time: 00:00:21.211" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "%%lang_python\n", "print (\"Hello World\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Use Cases\n", "\n", "We're envisioning a number of use cases for the SQL notebooks. In many ways it's simply the next generation experience for the query editor, and many of the things you can do in a plain editor can be done as well or better in a notebook. But a few scenarios have jumped out at us:\n", "\n", "- Teaching Tools \n", "- Runbooks\n", "- Business reporting and presentations\n", "- Troubleshooting\n", "- Deployments\n", "- Baselining\n", "\n", "We're excited to learn what the community can do with them!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**Example Server Information Report**\n", "\n", "Run this report and save it to a known location to maintain a basic point in time inventory." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "--Server basics\n", "SELECT\n", " getutcdate() as DateRun, \n", " db_name() as DatabaseName,\n", " serverproperty('ServerName') as ServerName,\n", " serverproperty('InstanceName') as InstanceName,\n", " serverproperty('ComputerNamePhysicalNetBIOS') as PhysicalName,\n", " serverproperty('Edition') as Edition,\n", " serverproperty('ProductMajorVersion') as MajorVersion,\n", " serverproperty('ProductMinorVersion') as MinorVersion\n", "\n", "--Databases\n", "SELECT *\n", "from sys.databases" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "**More SQL Examples**\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "DECLARE @i INT, @c varchar(26);\n", "SELECT @i = 65, @c = '';\n", "WHILE (@i < 93)\n", "BEGIN\n", " SELECT @c = concat(@c,CHAR(@i))\n", " SET @i = @i + 1\n", "END\n", "\n", "\n", "SELECT @c as \"Letters\", len(@c) as \"Count\"" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "DROP TABLE IF EXISTS [dbo].[MyNotebookTable]\n", "CREATE TABLE [dbo].[MyNotebookTable]\n", "(\n", " [Id] INT IDENTITY NOT NULL PRIMARY KEY, -- Primary Key column\n", " [FirstValue] NVARCHAR(50) NOT NULL,\n", " [SecondValue] NVARCHAR(50) NOT NULL\n", ");\n", "\n", "PRINT 'Success: Created MyNotebookTable'\n" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "raiserror('Something bad happened!',0,1) with nowait;\n", "waitfor delay '00:00:05'\n", "raiserror('Something bad happened... again!',0,1) with nowait;" ] } ], "metadata": { "kernelspec": { "display_name": "SQL", "language": "sql", "name": "SQL" }, "language_info": { "name": "sql", "version": "" } }, "nbformat": 4, "nbformat_minor": 2 }