Merge pull request #23 from zbrookle/sql_guide

DOC: Add sql syntax guide

Author: zbrookle

README.md

@@ -2,6 +2,7 @@
 
 ![CI](https://github.com/zbrookle/dataframe_sql/workflows/CI/badge.svg)
 
+
 ## Installation
 
 ```bash
@@ -41,6 +42,81 @@ FALSE_SERIES = Series(data=[False for _ in range(0, dataframe_size)]))
 NONE_SERIES = Series(data=[None for _ in range(0, dataframe_size)]))
 ```
 
+### SQL Syntax
+The sql syntax for dataframe_sql is as follows:
+
+Select statement:
+
+```SQL
+SELECT [{ ALL | DISTINCT }]
+    { [ <expression> ] | <expression> [ [ AS ] <alias> ] } [, ...]
+[ FROM <from_item>  [, ...] ]
+[ WHERE <bool_expression> ]
+[ GROUP BY { <expression> [, ...] } ]
+[ HAVING <bool_expression> ]
+```
+
+Set operations:
+
+```SQL
+<select_statement1>
+{UNION [DISTINCT] | UNION ALL | INTERSECT [DISTINCT] | EXCEPT [DISTINCT] | EXCEPT ALL}
+<select_statment2>
+```
+
+Joins:
+
+```SQL
+INNER, CROSS, FULL OUTER, LEFT OUTER, RIGHT OUTER, FULL, LEFT, RIGHT
+```
+
+Order by and limit:
+
+```SQL
+<set>
+[ORDER BY <expression>]
+[LIMIT <number>]
+```
+
+Supported expressions and functions:
+```SQL
++, -, *, /
+```
+```SQL
+CASE WHEN <condition> THEN <result> [WHEN ...] ELSE <result> END
+```
+```SQL
+SUM, AVG, MIN, MAX
+```
+```SQL
+{RANK | DENSE_RANK} OVER([PARTITION BY (<expresssion> [, <expression>...)])
+```
+```SQL
+CAST (<expression> AS <data_type>)
+```
+*Anything in <> is meant to be some string <br>
+*Anything in [] is optional <br>
+*Anything in {} is grouped together
+
+### Supported Data Types for cast expressions include:
+* VARCHAR, STRING
+* INT16, SMALLINT
+* INT32, INT
+* INT64, BIGINT
+* FLOAT16
+* FLOAT32
+* FLOAT, FLOAT64
+* BOOL
+* DATETIME64, TIMESTAMP
+* CATEGORY
+* OBJECT
+
+*Data types in dataframe SQL support many different name for certain datatypes becuase
+popular SQL data types are not implemented with common names in pandas and other
+dataframe frameworks
+<br>
+**To make this less confusing all data types that are of the same size on the
+backend are grouped together in this list
 
 ## Issues that come from Pandas
 

dataframe_sql/grammar/sql.grammar

@@ -25,8 +25,6 @@ groupby_expr: expression -> group_by
 
 window_expr: [window_expr ","] _window_name "AS"i ( window_definition )
 
-SET_OP: "UNION"i [ ("ALL"i | "DISTINCT"i) ] | "INTERSECT"i "DISTINCT"i | "EXCEPT"i "DISTINCT"i
-
 from_item: NAME [ [ "AS"i ] alias ] -> table
             | join -> join
             | ( "(" query_expr ")" ) [ [ "AS"i ] alias ] -> subquery
@@ -85,6 +83,7 @@ TYPENAME:  "object"i
          | "datetime64"i
          | "timestamp"i
          | "category"i
+         | "string"i
 AGGREGATION.8: "sum"i | "avg"i | "min"i | "max"i
 alias: NAME -> alias_string
 _window_name: NAME

dataframe_sql/tests/pandas_sql_functionality_test.py

@@ -1367,7 +1367,8 @@ def test_sql_data_types():
             cast(avocado_id as category) as avocado_id_category,
             cast(date as datetime64) as date,
             cast(date as timestamp) as time,
-            cast(region as varchar) as region_varchar
+            cast(region as varchar) as region_varchar,
+            cast(region as string) as region_string
         from avocado
         """
     )
@@ -1389,6 +1390,7 @@ def test_sql_data_types():
     pandas_frame["date"] = pandas_frame["Date"].astype("datetime64")
     pandas_frame["time"] = pandas_frame["Date"].astype("datetime64")
     pandas_frame["region_varchar"] = pandas_frame["region"].astype("string")
+    pandas_frame["region_string"] = pandas_frame["region"].astype("string")
     pandas_frame = pandas_frame.drop(columns=["avocado_id", "Date", "region"])
 
     tm.assert_frame_equal(pandas_frame, my_frame)
@@ -1453,6 +1455,6 @@ def test_boolean_order_of_operations_with_parens():
 if __name__ == "__main__":
     register_env_tables()
 
-    test_boolean_order_of_operations_with_parens()
+    test_sql_data_types()
 
     remove_env_tables()