Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Reserved Keywords document #45

Merged
merged 6 commits into from
Jul 21, 2023
Merged

Add Reserved Keywords document #45

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8002e09
Add Reserved Keywords document
am357 Jul 17, 2023
dc71317
Update docs/reserved-keywords.adoc
am357 Jul 17, 2023
4156526
Address comments
am357 Jul 17, 2023
9052915
Address comments
am357 Jul 18, 2023
7a65f62
Change capitalizations
am357 Jul 18, 2023
d795e58
Update reserved-keywords-spec-version-2019.adoc
am357 Jul 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 278 additions & 0 deletions docs/reserved-keywords.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,278 @@
= PartiQL Reserved Keywords

Reserved keywords are part of PartiQL Language that are used by PartiQL to parse and understand PartiQL statements.
am357 marked this conversation as resolved.
Show resolved Hide resolved
PartiQL Language Grammar Reserved Keywords cannot be used in PartiQL statements as-is.
For example, the following query results in a _Syntax Error_ because `FROM` is a Reserved Keyword in PartiQL:

.Example 1. Invalid PartiQL Query with a Reserved Keyword
[source, sql]
----
SELECT t.FROM FROM <<{'ID': 1, 'FROM': 'NA'}, {'ID': 2, 'FROM': 'SA'}>> AS t;
----

In order to use Reserved Keywords in your PartiQL statements, use Quoted Identifiers as Example 2 shows:

.Example 2. Using Quoted Identifier as a Reserve Keyword in a PartiQL Statement.
[source, sql]
----
SELECT t."FROM" FROM <<{'ID': 1, 'FROM': 'NA'}, {'ID': 2, 'FROM': 'SA'}>> AS t;
alancai98 marked this conversation as resolved.
Show resolved Hide resolved
----

== Reserved Keywords
[NOTE]
====
Reserved Keywords are yet to be https://github.com/partiql/partiql-spec/issues/2[formally defined] in PartiQL Specification, therefore there may be some differences in different PartiQL implementations.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it could be helpful to make a version of this document for each PartiQL version and implementation listing the reserved keywords (at least the versions with differences).

This can be useful as PartiQL versions change and develop over time. I know we've had similar questions related to our builtin functions (e.g. does partiql-lang-kotlin-x.y.z support this builtin function?).

For reference Microsoft's SQL server has different pages for their different versions:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think putting two additional dimensions (i.e., implementation and version) brings too much overhead unless we have a clear spec. definition for this. I see this document's objective to give a general list of possible keywords and a way to escape them while mentioning that the actual keywords can be different.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps a good compromise is adding PartiQL Spec. Version?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it could add overhead. I still think we should document somewhere though each implementation + implementation version's reserved keywords since they may change and add more keywords over time. Perhaps for each implementation we can have a doc listing the reserved keywords. As we perform new tagged releases on GitHub, we'll then have a link to the reserved keywords of that specific PartiQL version.

E.g. if we had a document called reserved-keywords.adoc in partiql-lang-kotlin, we could reference it like:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I generally agree, but I think we need to automate this using the Grammar in the code.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we could add an issue for each implementation to

  • make a reserved keywords doc listing all the reserved keywords
  • have some way to automate this doc?
    I think it can still be helpful to have the reserved keywords of each implementation/version visible

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just reflecting the offline response:

I think the following note should be sufficient:

Reserved keywords are yet to be https://github.com/partiql/partiql-spec/issues/2[formally defined] in PartiQL Specification, therefore there may be some differences in different PartiQL implementations.

I’m hesitant to go to a lower level b/c that increases the likelihood of exposing stale information if for example, Rust grammar changes.

I still think we need a story around versioned docs for implementations though and I’m going to open an issue for that.

Will update this thread with the issue.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is the issue for tracking the version-based documentation:
#46

====

[cols="1,1,1,1",grid=none, frame=none]
|===

|ABSOLUTE
alancai98 marked this conversation as resolved.
Show resolved Hide resolved
|ACTION
|ADD
|ALL
|ALLOCATE
|ALTER
|AND
|ANY
|ARE
|AS
|ASC
|ASSERTION
|AT
|AUTHORIZATION
|AVG
|BEGIN
|BETWEEN
|BIT
|BIT_LENGTH
|BY
|CAN_CAST
|CAN_LOSSLESS_CAST
|CASCADE
|CASCADED
|CASE
|CAST
|CATALOG
|CHAR
|CHARACTER
|CHARACTER_LENGTH
|CHAR_LENGTH
|CHECK
|CLOSE
|COALESCE
|COLLATE
|COLLATION
|COLUMN
|COMMIT
|CONFLICT
|CONNECT
|CONNECTION
|CONSTRAINT
|CONSTRAINTS
|CONTINUE
|CONVERT
|CORRESPONDING
|COUNT
|CREATE
|CROSS
|CURRENT
|CURRENT_DATE
|CURRENT_TIME
|CURRENT_TIMESTAMP
|CURRENT_USER
|CURSOR
|DATE
|DATE_ADD
|DATE_DIFF
|DEALLOCATE
|DEC
|DECIMAL
|DECLARE
|DEFAULT
|DEFERRABLE
|DEFERRED
|DELETE
|DESC
|DESCRIBE
|DESCRIPTOR
|DIAGNOSTICS
|DISCONNECT
|DISTINCT
|DO
|DOMAIN
|DOUBLE
|DROP
|ELSE
|END
|END-EXEC
|END_EXEC
|ESCAPE
|EXCEPT
|EXCEPTION
|EXCLUDED
|EXEC
|EXECUTE
|EXISTS
|EXPLAIN
|EXTERNAL
|EXTRACT
|FALSE
|FETCH
|FIRST
|FLOAT
|FOR
|FOREIGN
|FOUND
|FROM
|FULL
|GET
|GLOBAL
|GO
|GOTO
|GRANT
|GROUP
|HAVING
|IDENTITY
|IMMEDIATE
|IN
|INDEX
|INDICATOR
|INITIALLY
|INNER
|INPUT
|INSENSITIVE
|INSERT
|INT
|INTEGER
|INTERSECT
|INTERVAL
|INTO
|IS
|ISOLATION
|JOIN
|KEY
|LAG
|LANGUAGE
|LAST
|LATERAL
|LEAD
|LEFT
|LET
|LEVEL
|LIKE
|LIMIT
|LOCAL
|LOWER
|MATCH
|MAX
|MIN
|MISSING
|MODIFIED
|MODULE
|NAMES
|NATIONAL
|NATURAL
|NCHAR
|NEW
|NEXT
|NO
|NOT
|NOTHING
|NULL
|NULLIF
|NULLS
|NUMERIC
|OCTET_LENGTH
|OF
|OFFSET
|OLD
|ON
|ONLY
|OPEN
|OPTION
|OR
|ORDER
|OUTER
|OUTPUT
|OVER
|OVERLAPS
|OVERLAY
|PAD
|PARTIAL
|PARTITION
|PIVOT
|PLACING
|POSITION
|PRECISION
|PREPARE
|PRESERVE
|PRIMARY
|PRIOR
|PRIVILEGES
|PROCEDURE
|PUBLIC
|READ
|REAL
|REFERENCES
|RELATIVE
|REMOVE
|REPLACE
|RESTRICT
|RETURNING
|REVOKE
|RIGHT
|ROLLBACK
|ROWS
|SCHEMA
|SCROLL
|SECTION
|SELECT
|SESSION
|SESSION_USER
|SET
|SHORTEST
|SIZE
|SMALLINT
|SOME
|SPACE
|SQL
|SQLCODE
|SQLERROR
|SQLSTATE
|SUBSTRING
|SUM
|SYSTEM_USER
|TABLE
|TEMPORARY
|THEN
|TIME
|TIMESTAMP
|TO
|TRANSACTION
|TRANSLATE
|TRANSLATION
|TRIM
|TRUE
|UNION
|UNIQUE
|UNKNOWN
|UNPIVOT
|UPDATE
|UPPER
|UPSERT
|USAGE
|USER
|USING
|VALUE
|VALUES
|VARCHAR
|VARYING
|VIEW
|WHEN
|WHENEVER
|WHERE
|WITH
|WORK
|WRITE
|ZONE