diff --git a/ai-prompts/documentation.md b/ai-prompts/documentation.md new file mode 100644 index 00000000..5ffc4960 --- /dev/null +++ b/ai-prompts/documentation.md @@ -0,0 +1,5 @@ +Our documentation for the `noql` syntax is stored in organised and separate Markdown files at `/docs/docs/sql-syntax/` folder, we also have a collection of tests in the `/test/` folder that show how to use the library. + +All of the functions that are listed as the return value from the function call `functionMappings()` located in the `/lib/MongoFunctions.js` file should be documented in the Markdown files referred to above. + +Please can you update the documentation in the `/docs/docs/sql-syntax/` folder, so that any functions which are missing are documented. The newly generated documents should be documented in the same way as the existing markdown files are. Please don't create any new files, I want you to update the existing ones. For each of the new functions you are documenting, please put it in the most appropriate of the existing files. The only exception to this is the `pivot` and `unpivot` operations which should be in a new file called `pivot-unpivot.md` diff --git a/docs/docs/sql-syntax/arrays.md b/docs/docs/sql-syntax/arrays.md index 28938860..09390954 100644 --- a/docs/docs/sql-syntax/arrays.md +++ b/docs/docs/sql-syntax/arrays.md @@ -10,8 +10,8 @@ NoQL uses sub-selects with a FROM array field to query array fields in collectio ```sql SELECT - (SELECT * FROM Rentals WHERE staffId=2) AS t - FROM + (SELECT * FROM Rentals WHERE staffId=2) AS t + FROM `customers` ``` @@ -20,9 +20,9 @@ Using '$$ROOT' in sub select promotes the field to the root value of the array ???+ example "Using '$$ROOT' in sub select" ```sql - SELECT - (SELECT filmId AS '$$ROOT' FROM Rentals WHERE staffId=2) AS t - FROM + SELECT + (SELECT filmId AS '$$ROOT' FROM Rentals WHERE staffId=2) AS t + FROM `customers` ``` @@ -31,9 +31,9 @@ Slicing the array is supported by limit and offset in queries ???+ example "Slicing an array with limit and offset" ```sql - SELECT - (SELECT * FROM Rentals WHERE staffId=2 LIMIT 10 OFFSET 5) AS t - FROM + SELECT + (SELECT * FROM Rentals WHERE staffId=2 LIMIT 10 OFFSET 5) AS t + FROM `customers` ``` @@ -46,15 +46,15 @@ Sorting Arrays is supported in MongoDB 5.2+ and NoQL (SELECT * FROM Rentals ORDER BY id DESC) AS totalRentals FROM customers ``` - + !!! warning "Aggregation functions are not supported in a sub select" - Aggregation functions are not supported in a sub select. For example, the following won't work - ```sql +Aggregation functions are not supported in a sub select. For example, the following won't work +`sql --Wont'Work SELECT id, (SELECT count(*) AS count FROM Rentals) AS totalRentals FROM customers - ``` + ` ## UNWIND Function @@ -65,28 +65,29 @@ NoQL has a high level unwind function that will unwind array fields. For Joins, ???+ example "UNWIND in SELECT" ```sql - SELECT + SELECT field1, UNWIND(arrFld) as arrFld FROM test ``` + ???+ example "Complex UNWIND" ```sql - SELECT + SELECT MERGE_OBJECTS( - (SELECT + (SELECT t.CustomerID ,t.Name ) ,t.Rental - ) AS `$$ROOT` - FROM - (SELECT + ) AS `$$ROOT` + FROM + (SELECT id AS CustomerID ,`First Name` AS Name - ,UNWIND(Rentals) AS Rental + ,UNWIND(Rentals) AS Rental FROM customers) AS t ``` @@ -161,6 +162,7 @@ Converts the array to an object. ARRAY_TO_OBJECT(OBJECT_TO_ARRAY(`Address`)) AS test FROM `customers`; ``` + ### CONCAT_ARRAYS `CONCAT_ARRAYS(array expr,...)` @@ -174,6 +176,7 @@ Concatenate the provided list of arrays. CONCAT_ARRAYS((SELECT `Film Title` AS ‘$$ROOT’ FROM `Rentals`), ARRAY_RANGE(0,10,2)) AS test FROM `customers`; ``` + ### FIRST_IN_ARRAY `FIRST_IN_ARRAY(array expr)` @@ -229,6 +232,7 @@ Returns the last element of an array. LAST_IN_ARRAY(`Rentals`) AS test FROM `customers`; ``` + ### OBJECT_TO_ARRAY `OBJECT_TO_ARRAY(expr)` @@ -362,8 +366,8 @@ Sums the values in an array given an array field or sub-select and the field to `First Name`, `Last Name`, SUM_ARRAY( - (SELECT - SUM_ARRAY(`Payments`, ‘Amount’) AS total + (SELECT + SUM_ARRAY(`Payments`, ‘Amount’) AS total FROM `Rentals`), ‘total’) AS t FROM customers; ``` diff --git a/docs/docs/sql-syntax/date-functions.md b/docs/docs/sql-syntax/date-functions.md index 2ce132fa..7983c9ee 100644 --- a/docs/docs/sql-syntax/date-functions.md +++ b/docs/docs/sql-syntax/date-functions.md @@ -11,8 +11,8 @@ Returns the current date !!! example ```sql - SELECT - CURRENT_DATE() AS exprVal + SELECT + CURRENT_DATE() AS exprVal FROM `customers` ``` @@ -28,8 +28,8 @@ Constructs and returns a Date object given the date’s constituent ISO properti !!! example ```sql - SELECT - DATE_FROM_ISO_PARTS(2017, 6, 3, null, null, null, null, null) AS exprVal + SELECT + DATE_FROM_ISO_PARTS(2017, 6, 3, null, null, null, null, null) AS exprVal FROM `customers` ``` @@ -42,8 +42,8 @@ Constructs and returns a Date object given the date’s constituent properties. !!! example ```sql - SELECT - DATE_FROM_PARTS(2021, 11, 15, null, null, null, null, null) AS exprVal + SELECT + DATE_FROM_PARTS(2021, 11, 15, null, null, null, null, null) AS exprVal FROM `customers` ``` @@ -56,8 +56,8 @@ Converts a date/time string to a date object. !!! example ```sql - SELECT - DATE_FROM_STRING('2021-11-15T14:43:29.000Z', null, null) AS exprVal + SELECT + DATE_FROM_STRING('2021-11-15T14:43:29.000Z', null, null) AS exprVal FROM `customers` ``` @@ -70,8 +70,8 @@ Returns a document that contains the constituent parts of a given Date value. !!! example ```sql - SELECT - DATE_TO_PARTS(DATE_FROM_STRING('2021-11-15T14:43:29.000Z'), null, true) AS exprVal + SELECT + DATE_TO_PARTS(DATE_FROM_STRING('2021-11-15T14:43:29.000Z'), null, true) AS exprVal FROM `customers` ``` @@ -84,7 +84,7 @@ Converts a date object to a string according to a user-specified format. !!! example ```sql - SELECT + SELECT DATE_TO_STRING(DATE_FROM_STRING('2021-11-15T14:43:29.000Z'), null, null) AS exprVal FROM `customers` ``` @@ -98,8 +98,8 @@ Returns the day of the month for a date as a number between 1 and 31. !!! example ```sql - SELECT - DAY_OF_MONTH(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + DAY_OF_MONTH(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -112,12 +112,11 @@ Returns the day of the week for a date as a number between 1 (Sunday) and 7 (Sat !!! example ```sql - SELECT - DAY_OF_WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + DAY_OF_WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` - ### DAY_OF_YEAR `#!sql DAY_OF_YEAR(expr)` @@ -127,8 +126,8 @@ Returns the day of the year for a date as a number between 1 and 366. !!! example ```sql - SELECT - DAY_OF_YEAR(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + DAY_OF_YEAR(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -141,10 +140,11 @@ Returns the hour portion of a date as a number between 0 and 23. !!! example ```sql - SELECT - HOUR(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + HOUR(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` + ### ISO_DAY_OF_WEEK `#!sql ISO_DAY_OF_WEEK(expr)` @@ -154,22 +154,22 @@ Returns the weekday number in ISO 8601 format, ranging from 1 (for Monday) to 7 !!! example ```sql - SELECT - ISO_DAY_OF_WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + ISO_DAY_OF_WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` + ### ISO_WEEK `#!sql ISO_WEEK(expr)` Returns the week number in ISO 8601 format, ranging from 1 to 53. Week numbers start at 1 with the week (Monday through Sunday) that contains the year’s first Thursday. - !!! example ```sql - SELECT - ISO_WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + ISO_WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -180,13 +180,13 @@ Returns the week number in ISO 8601 format, ranging from 1 to 53. Week numbers s Returns the year number in ISO 8601 format. The year starts with the Monday of week 1 and ends with the Sunday of the last week. !!! example + ```sql - SELECT - ISO_WEEK_YEAR(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + ISO_WEEK_YEAR(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` - ### MILLISECOND `#!sql MILLISECOND(expr)` @@ -196,8 +196,8 @@ Returns the millisecond portion of a date as an integer between 0 and 999. !!! example ```sql - SELECT - MILLISECOND(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + MILLISECOND(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -210,10 +210,11 @@ Returns the minute portion of a date as a number between 0 and 59. !!! example ```sql - SELECT - MINUTE(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + MINUTE(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` + ### MONTH `#!sql MONTH(expr)` @@ -223,8 +224,8 @@ Returns the month of a date as a number between 1 and 12. !!! example ```sql - SELECT - MONTH(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + MONTH(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -237,8 +238,8 @@ Returns the second portion of a date as a number between 0 and 59, but can be 60 !!! example ```sql - SELECT - SECOND(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + SECOND(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -251,8 +252,8 @@ Returns the week of the year for a date as a number between 0 and 53. !!! example ```sql - SELECT - WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + WEEK(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -265,8 +266,8 @@ Returns the year portion of a date. !!! example ```sql - SELECT - YEAR(DATE_FROM_STRING('2021-11-15')) AS exprVal + SELECT + YEAR(DATE_FROM_STRING('2021-11-15')) AS exprVal FROM `customers` ``` @@ -279,10 +280,118 @@ Extracts a portion of the date as per Postgres standard. Supported time periods: !!! example ```sql - SELECT + SELECT EXTRACT(year from orderDate) AS year ,EXTRACT(month from orderDate) AS month - ,EXTRACT(day from TO_DATE('2021-10-23')) AS day - FROM + ,EXTRACT(day from TO_DATE('2021-10-23')) AS day + FROM orders" ``` + +### DATE_ADD + +`DATE_ADD(date, unit, amount, [timezone])` + +Adds a specified time interval to a date. + +???+ example "Example `DATE_ADD` usage" + + ```sql + SELECT + id, + item, + orderDate as od1, + DATE_ADD(orderDate, 'hour', 2) as od2 + FROM orders + WHERE id = 2 + LIMIT 1 + ``` + +You can also use the alias `DATEADD`: + +### DATE_SUBTRACT + +`DATE_SUBTRACT(date, unit, amount, [timezone])` + +Subtracts a specified time interval from a date. + +???+ example "Example `DATE_SUBTRACT` usage" + + ```sql + SELECT + id, + item, + orderDate as od1, + DATE_SUBTRACT(orderDate, 'hour', 2) as od2 + FROM orders + WHERE id = 2 + LIMIT 1 + ``` + +You can also use the alias `DATESUBTRACT`: + +### DATE_DIFF + +`DATE_DIFF(startDate, endDate, unit, [timezone], [startOfWeek])` + +Calculates the difference between two dates in the specified unit. + +???+ example "Example `DATE_DIFF` usage" + + ```sql + SELECT + id, + item, + orderDate, + CURRENT_DATE() as now, + DATE_DIFF(orderDate, DATE_ADD(orderDate, 'day', 2), 'day') as diff + FROM orders + WHERE id = 2 + LIMIT 1 + ``` + +You can also use the alias `DATEDIFF`: + +### DATE_TRUNC + +`DATE_TRUNC(date, unit)` + +Truncates a date to the specified unit of granularity. + +???+ example "Example `DATE_TRUNC` usage" + + ```sql + SELECT + orderDate, + DATE_TRUNC(orderDate, 'month') as monthStart, + DATE_TRUNC(orderDate, 'year') as yearStart + FROM orders + LIMIT 5 + ``` + +The `unit` parameter can be one of the following: + +- 'year' +- 'quarter' +- 'month' +- 'week' +- 'day' +- 'hour' +- 'minute' +- 'second' +- 'millisecond' + +This function is useful for grouping dates by a specific time unit or for finding the start of a time period. + +???+ example "Example `DATE_TRUNC` usage in grouping" + + ```sql + SELECT + DATE_TRUNC(orderDate, 'month') as monthStart, + COUNT(*) as orderCount + FROM orders + GROUP BY DATE_TRUNC(orderDate, 'month') + ORDER BY monthStart + ``` + +This query groups orders by month and counts the number of orders in each month. diff --git a/docs/docs/sql-syntax/objects.md b/docs/docs/sql-syntax/objects.md index 0e050350..8e5a3b75 100644 --- a/docs/docs/sql-syntax/objects.md +++ b/docs/docs/sql-syntax/objects.md @@ -86,4 +86,31 @@ Parses the JSON string. Use in conjunction with `ARRAY_TO_OBJECT` to convert an FROM `customers`; ``` +### EMPTY_OBJECT +`EMPTY_OBJECT()` + +Creates an empty object. + +???+ example "Example `EMPTY_OBJECT` usage" + + ```sql + SELECT + id, + EMPTY_OBJECT() AS emptyObj, + MERGE_OBJECTS(EMPTY_OBJECT(), `Address`) AS filledObj + FROM `customers`; + ``` + +???+ example "Example `EMPTY_OBJECT` usage in a condition" + + ```sql + SELECT + id, + `Address`, + CASE + WHEN `Address` = EMPTY_OBJECT() THEN 'No Address' + ELSE 'Has Address' + END AS addressStatus + FROM `customers`; + ``` diff --git a/docs/docs/sql-syntax/pivot-unpivot.md b/docs/docs/sql-syntax/pivot-unpivot.md new file mode 100644 index 00000000..f8f9fb97 --- /dev/null +++ b/docs/docs/sql-syntax/pivot-unpivot.md @@ -0,0 +1,72 @@ +# Pivot and Unpivot Operations + +## PIVOT + +The `PIVOT` operation allows you to transform rows into columns, creating a cross-tabular format. In NoQL, the PIVOT operation is specified as a hint on the subquery. + +???+ example "Example `PIVOT` usage" + + ```sql + SELECT 'AverageCost' as CostSortedByProductionDays, + "0", + "1", + "2", + "3", + "4" + FROM ( + SELECT DaysToManufacture, + StandardCost + FROM Production_Product + GROUP BY DaysToManufacture, StandardCost + ORDER BY DaysToManufacture, StandardCost + ) 'pvt|pivot([avg(StandardCost) as AverageCost],DaysToManufacture,[0,1,2,3,4])' + ``` + +The PIVOT hint has the following format: +`'pvt|pivot([aggregate_function(column) as alias], pivot_column, [pivot_values])'` + +- `aggregate_function(column) as alias`: Specifies the aggregation to be performed and the alias for the result. +- `pivot_column`: The column whose values will become new columns. +- `pivot_values`: An array of values from the pivot column that will become new columns. + +## UNPIVOT + +The `UNPIVOT` operation is the reverse of `PIVOT`. It transforms columns into rows, converting a cross-tabular format back into a normalized form. In NoQL, the UNPIVOT operation is also specified as a hint on the subquery. + +???+ example "Example `UNPIVOT` usage" + + ```sql + SELECT VendorID, Employee, Orders + FROM ( + SELECT VendorID, Emp1, Emp2, Emp3, Emp4, Emp5, unset(_id) + FROM pvt + ) 'unpvt|unpivot(Orders,Employee,[Emp1, Emp2, Emp3, Emp4, Emp5])' + ORDER BY VendorID, Employee + ``` + +The UNPIVOT hint has the following format: +`'unpvt|unpivot(value_column, name_column, [column_list])'` + +- `value_column`: The name of the new column that will contain the unpivoted values. +- `name_column`: The name of the new column that will contain the names of the original columns. +- `column_list`: An array of column names to be unpivoted. + +Multiple UNPIVOT operations can be chained using the pipe (`|`) character: + +???+ example "Example of multiple `UNPIVOT` operations" + + ```sql + SELECT SalesID, + ROW_NUMBER() OVER ( + ORDER BY OrderName + ) OrderNum, + OrderName, + OrderDate, + OrderAmt + FROM ( + SELECT SalesID, Order1Name, Order2Name, Order1Date, Order2Date, Order1Amt, Order2Amt, unset(_id) + FROM multiple-unpivot + ) 'unpvt|unpivot(OrderName,OrderNames,[Order1Name, Order2Name])|unpivot(OrderDate,OrderDates,[Order1Date, Order2Date])|unpivot(OrderAmt,OrderAmts,[Order1Amt, Order2Amt])' + ``` + +Note: The exact capabilities and performance of `PIVOT` and `UNPIVOT` operations may depend on the specific implementation in NoQL and the underlying MongoDB version. diff --git a/docs/docs/sql-syntax/string-functions.md b/docs/docs/sql-syntax/string-functions.md index 4d9f6a8d..b57ae404 100644 --- a/docs/docs/sql-syntax/string-functions.md +++ b/docs/docs/sql-syntax/string-functions.md @@ -253,3 +253,52 @@ Finds the first index of the substring within the expression. Returns 0 if not f WHERE LOCATE(Title,'B') > 0; ``` + +### LEFT + +`LEFT(expr, length)` + +Returns the leftmost characters from the expression. + +???+ example "Example `LEFT` usage" + + ```sql + SELECT + LEFT(`First Name`, 3) AS firstThreeChars + FROM `customers`; + ``` + +### STARTS_WITH + +`STARTS_WITH(expr, prefix)` + +Returns true if the expression starts with the specified prefix. + +???+ example "Example `STARTS_WITH` usage" + + ```sql + SELECT + id, + `First Name`, + STARTS_WITH(`First Name`, 'Jo') AS startsWithJo + FROM `customers`; + ``` + +### WRAP_PARAM + +`WRAP_PARAM(expr, [forceString])` + +Wraps a parameter, typically used for handling special characters or ensuring correct interpretation of a string. + +???+ example "Example `WRAP_PARAM` usage" + + ```sql + SELECT + WRAP_PARAM('Hello, "World"!') as wrappedString, + WRAP_PARAM(42, true) as wrappedNumber + FROM + `customers` + LIMIT 1 + ``` + +In this example, `WRAP_PARAM` ensures that the string with quotes is properly handled, and when `forceString` is set to true, it forces the number to be treated as a string. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 90486c32..dc3c71a3 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -116,6 +116,7 @@ nav: - Window Functions: sql-syntax/window-functions.md - Limits and Offsets: sql-syntax/limits-and-offsets.md - Union: sql-syntax/union.md + - Pivot And Unpivot: sql-syntax/pivot-unpivot.md - Playground: playground/index.md - JS Library: - Getting Started: js-library/getting-started.md