Init

Author: Antony Bailey

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Standard Query Language
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,53 @@
+# Standard Query Language (SQLY)
+
+**SQLY** is a YAML-based query language inspired by JQL, Kusto, and DQL. It is designed for querying structured and semi-structured data efficiently.
+
+## 📖 Specification Overview
+
+### 🔹 [Basics](basics.md)
+
+Learn how to write simple SQLY queries, including `select`, `from`, `where`, `order_by`, and `group_by`.
+
+### 🔹 [Advanced Features](advanced_features.md)
+
+Explore complex filtering, logical operators, sorting, and aggregations.
+
+### 🔹 [Subqueries](subqueries.md)
+
+Use subqueries to fetch results dynamically within a query.
+
+### 🔹 [Common Table Expressions (CTEs)](ctes.md)
+
+Utilize CTEs to structure queries for better readability and performance.
+
+### 🔹 [Window Functions](window_functions.md)
+
+Perform ranking, running totals, and moving averages using window functions.
+
+### 🔹 [Recursive Queries](recursive_queries.md)
+
+Handle hierarchical data, such as employee relationships or category trees.
+
+### 🔹 [Full-text Search](full_text_search.md)
+
+Perform fuzzy searches and text matching in large datasets.
+
+### 🔹 [Geospatial Queries](geospatial_queries.md)
+
+Work with geospatial data to find points within a radius, bounding boxes, and distances.
+
+### 🔹 [Machine Learning](machine_learning.md)
+
+Integrate predictive models for forecasting and anomaly detection within queries.
+
+## 🚀 Getting Started
+
+To start using SQLY, check out the [Basics](basics.md) section and explore examples.
+
+## 📌 Contributions
+
+Contributions are welcome! Feel free to submit PRs or issues for improvements.
+
+## 📜 License
+
+This project is licensed under the MIT License.

advanced_features.md

@@ -0,0 +1,118 @@
+# SQLY Advanced Features
+
+## 📖 Introduction
+
+This section covers advanced SQLY features, including complex filtering, sorting, joins, pagination, and more.
+
+---
+
+## 🔎 Complex Filtering with Logical Operators
+
+SQLY supports combining multiple conditions using `and`, `or`, and `not`.
+
+### ✅ Example 1: Fetch Users with Multiple Conditions
+
+```yaml
+query:
+  select: [id, name, email]
+  from: users
+  where:
+    and:
+      - status: active
+      - role: admin
+      - last_login:
+          gte: "2024-01-01"
+```
+
+### ✅ Example 2: Fetch Orders Matching Multiple Statuses
+
+```yaml
+query:
+  select: [order_id, customer, total_price, status]
+  from: orders
+  where:
+    or:
+      - status: completed
+      - status: shipped
+```
+
+---
+
+## 📊 Sorting & Pagination
+
+Sorting results and limiting the number of returned rows.
+
+### ✅ Example 3: Sort Users by Last Login Date (Descending)
+
+```yaml
+query:
+  select: [id, name, last_login]
+  from: users
+  order_by: last_login DESC
+  limit: 20
+```
+
+### ✅ Example 4: Paginate Results (Second Page, 10 Results per Page)
+
+```yaml
+query:
+  select: [id, name, created_at]
+  from: users
+  limit: 10
+  offset: 10
+```
+
+---
+
+## 🔗 Joining Tables
+
+SQLY supports joining multiple tables.
+
+### ✅ Example 5: Fetch Orders with Customer Names
+
+```yaml
+query:
+  select: [orders.order_id, customers.name, orders.total_price]
+  from: orders
+  join:
+    customers:
+      on: orders.customer_id = customers.id
+```
+
+---
+
+## 🔍 Searching with `like` and `full_text_search`
+
+Perform searches based on text patterns.
+
+### ✅ Example 6: Find Products Containing "Wireless"
+
+```yaml
+query:
+  select: [id, name, description]
+  from: products
+  where:
+    name:
+      like: "%wireless%"
+```
+
+### ✅ Example 7: Full-Text Search on Articles
+
+```yaml
+query:
+  select: [id, title, content]
+  from: articles
+  where:
+    content:
+      full_text_search: "machine learning"
+```
+
+---
+
+## 📌 Summary
+
+- Use `and`, `or`, `not` for complex filtering.
+- `order_by` sorts results.
+- `limit` and `offset` enable pagination.
+- `join` allows querying across tables.
+- `like` and `full_text_search` support text searches.

basics.md

@@ -0,0 +1,109 @@
+# SQLY Basics
+
+## 📖 Introduction
+
+SQLY (Standard Query Language) is a YAML-based query language designed for structured and semi-structured data. It is inspired by JQL, Kusto, and DQL while offering a human-readable syntax.
+
+---
+
+## 🛠 Basic Query Structure
+
+A simple SQLY query consists of the following components:
+
+- `select`: Specifies the fields to retrieve.
+- `from`: Defines the data source.
+- `where`: Filters the results.
+- `order_by`: Sorts the results.
+- `limit`: Limits the number of returned rows.
+
+### ✅ Example 1: Fetch Active Users
+
+```yaml
+query:
+  select: [id, name, email]
+  from: users
+  where:
+    status: active
+  order_by: name ASC
+  limit: 50
+```
+
+### ✅ Example 2: Fetch Orders Above a Certain Price
+
+```yaml
+query:
+  select: [order_id, customer, total_price]
+  from: orders
+  where:
+    total_price:
+      gt: 100
+  order_by: total_price DESC
+```
+
+---
+
+## 🔍 Filtering & Logical Operators
+
+SQLY supports multiple conditions using logical operators:
+
+| Operator | Description |
+|----------|------------|
+| `gt` | Greater than |
+| `lt` | Less than |
+| `gte` | Greater than or equal |
+| `lte` | Less than or equal |
+| `in` | Matches any value in a list |
+| `not` | Negates a condition |
+
+### ✅ Example 3: Fetch High-Value Orders from Specific Customers
+
+```yaml
+query:
+  select: [order_id, customer, total_price]
+  from: orders
+  where:
+    total_price:
+      gte: 500
+    customer:
+      in: ["Alice", "Bob", "Charlie"]
+```
+
+### ✅ Example 4: Fetch Users Who Are Not Admins
+
+```yaml
+query:
+  select: [id, name]
+  from: users
+  where:
+    role:
+      not: admin
+```
+
+---
+
+## 📊 Aggregation & Grouping
+
+SQLY allows aggregation functions with `group_by`.
+
+### ✅ Example 5: Calculate Average Order Value per Customer
+
+```yaml
+query:
+  select:
+    - customer_id
+    - avg: total_price
+  from: orders
+  group_by: customer_id
+```
+
+---
+
+## 📌 Summary
+
+- Use `select` to define fields.
+- `from` specifies the data source.
+- `where` applies filtering.
+- Use `order_by` for sorting results.
+- Apply `group_by` for aggregations.
+
+Proceed to **[Advanced Features](advanced_features.md)** to explore more capabilities.

ctes.md

@@ -0,0 +1,84 @@
+# SQLY Common Table Expressions (CTEs)
+
+## 📖 Introduction
+
+Common Table Expressions (CTEs) provide a way to define temporary, reusable query structures within a single SQLY query. They improve readability and make complex queries more maintainable.
+
+---
+
+## 🔍 Defining a CTE
+
+CTEs are defined using the `with` keyword, followed by a name and a subquery.
+
+### ✅ Example 1: Using a CTE to Find High-Value Orders
+
+```yaml
+query:
+  with:
+    high_value_orders:
+      select: [order_id, customer_id, total_price]
+      from: orders
+      where:
+        total_price:
+          gt: 1000
+  select: *
+  from: high_value_orders
+```
+
+---
+
+## 🔗 Using Multiple CTEs
+
+You can define multiple CTEs in a single query to modularize complex logic.
+
+### ✅ Example 2: Using Two CTEs to Analyze Customer Spending
+
+```yaml
+query:
+  with:
+    customer_totals:
+      select: [customer_id, sum: total_price as total_spent]
+      from: orders
+      group_by: customer_id
+    top_customers:
+      select: *
+      from: customer_totals
+      where:
+        total_spent:
+          gt: 5000
+  select: *
+  from: top_customers
+```
+
+---
+
+## 🔁 Recursive CTEs
+
+Recursive CTEs allow querying hierarchical data such as organizational structures or category trees.
+
+### ✅ Example 3: Querying an Employee Hierarchy
+
+```yaml
+query:
+  with:
+    employee_hierarchy:
+      select: [id, name, manager_id]
+      from: employees
+      where:
+        manager_id: null
+      union_all:
+        select: [e.id, e.name, e.manager_id]
+        from: employees as e
+        join: employee_hierarchy as eh
+          on: e.manager_id = eh.id
+  select: *
+  from: employee_hierarchy
+```
+
+---
+
+## 📌 Summary
+
+- CTEs allow defining temporary, reusable query structures.
+- Multiple CTEs can be combined to simplify complex queries.
+- Recursive CTEs enable hierarchical data processing.