From a023f49bc33764263eab23b6def9a323f39b06e3 Mon Sep 17 00:00:00 2001 From: Kate Tyrol Date: Wed, 3 Jul 2024 15:01:52 -0400 Subject: [PATCH] Expanded SQL Documentation Per Issue #7604 Expanded SQL documentation, basing terminology and level of detail on the assumption of an audience that is nearly or mostly new to SQL. --- Gemfile.lock | 7 ++++ .../course_management/sql_toolbox.md | 33 ++++++++++++++++--- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/Gemfile.lock b/Gemfile.lock index 47e66c36..b69bb55e 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -38,6 +38,7 @@ GEM faraday-net_http (3.1.0) net-http ffi (1.16.3) + ffi (1.16.3-x64-mingw-ucrt) forwardable-extended (2.6.0) gemoji (4.1.0) github-pages (231) @@ -233,6 +234,8 @@ GEM uri nokogiri (1.16.3-arm64-darwin) racc (~> 1.4) + nokogiri (1.16.3-x64-mingw-ucrt) + racc (~> 1.4) nokogiri (1.16.3-x86_64-linux) racc (~> 1.4) octokit (4.25.1) @@ -270,19 +273,23 @@ GEM unf (0.1.4) unf_ext unf_ext (0.0.9.1) + unf_ext (0.0.9.1-x64-mingw-ucrt) unicode-display_width (1.8.0) uri (0.13.0) + wdm (0.1.1) webrick (1.8.1) yell (2.2.2) PLATFORMS arm64-darwin-22 + x64-mingw-ucrt x86_64-linux DEPENDENCIES github-pages (= 231) html-proofer (~> 3.19.4) json + wdm (>= 0.1.1) webrick (~> 1.8) BUNDLED WITH diff --git a/_docs/instructor/course_management/sql_toolbox.md b/_docs/instructor/course_management/sql_toolbox.md index e22f9131..7a29c098 100644 --- a/_docs/instructor/course_management/sql_toolbox.md +++ b/_docs/instructor/course_management/sql_toolbox.md @@ -5,12 +5,39 @@ redirect_from: - /instructor/sql_toolbox --- -While Submitty provides mechanisms of getting information about a course, or grades, an -instructor may wish to run one-off queries against their database. To facilitate this, +While Submitty already provides information about courses and grades, an +instructor may wish to run one-off queries against Submitty's database in order to see +information in a format of their own choosing. To facilitate this, Submitty provides for each course a "SQL Toolbox" that can be accessed from the sidebar. Within the toolbox, instructors may run a `SELECT` query and see the results in tabular format. +![](/images/sql_toolbox.png) +### Basic Use +The button labeled "Database Schema Documentation" at the top of the SQL Toolbox page +contains details of all the information stored by Submitty and how these different +pieces of information relate to one another. + +One simple query you can use the SQL toolbox for is to check what assignment IDs you've already used when trying to decide on a new one. The code for that looks like: +```TSQL +SELECT g_id from gradeable +``` +If you have a lot of gradeables, it might help to sort the output of that code like so: +```TSQL +SELECT g_id from gradeable ORDER BY g_id +``` +### Outside Learning Sources +If you're brand new to writing SQL queries, here are a couple of popular resources for learning: + +[SQL Bolt](https://sqlbolt.com/) + +[w3 Schools](https://www.w3schools.com/sql/sql_intro.asp) +### Advanced Use +Once you're comfortable with writing SQL and have explored the database schema documentation some, you can start to write more complex queries. The query below shows all comments that have been written on all submissions from one student (username dents5 for this example): +```TSQL +SELECT comm.*, g.g_grade_due_date FROM gradeable_data_overall_comment comm INNER JOIN gradeable g ON comm.g_id = g.g_id WHERE comm.goc_user_id = 'dents5' ORDER BY comm.g_id +``` +### Limitations The toolbox does come with a number of important limitations, put in place to help prevent accidental data loss and general security. As such, the toolbox will: @@ -19,5 +46,3 @@ prevent accidental data loss and general security. As such, the toolbox will: * only run one query at a time. Attempting to run two queries separated by `;` will return an error. * run each query inside of a transaction that is rolled back and never committed. - -![](/images/sql_toolbox.png)