summaryrefslogtreecommitdiffstats
path: root/pdoc/docs/expressions.md
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2023-01-04 07:24:08 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-01-04 07:24:08 +0000
commit7a2201963d5b03bd1828d350ccaecb4eda30d30c (patch)
tree19effbe90b8d78fdcb5f7d4bd0dd46b177ffdaab /pdoc/docs/expressions.md
parentReleasing debian version 10.2.9-1. (diff)
downloadsqlglot-7a2201963d5b03bd1828d350ccaecb4eda30d30c.tar.xz
sqlglot-7a2201963d5b03bd1828d350ccaecb4eda30d30c.zip
Merging upstream version 10.4.2.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'pdoc/docs/expressions.md')
-rw-r--r--pdoc/docs/expressions.md41
1 files changed, 41 insertions, 0 deletions
diff --git a/pdoc/docs/expressions.md b/pdoc/docs/expressions.md
new file mode 100644
index 0000000..c82674b
--- /dev/null
+++ b/pdoc/docs/expressions.md
@@ -0,0 +1,41 @@
+# Expressions
+
+Every AST node in SQLGlot is represented by a subclass of `Expression`. Each such expression encapsulates any necessary context, such as its child expressions, their names, or arg keys, and whether each child expression is optional or not.
+
+Furthermore, the following attributes are common across all expressions:
+
+#### key
+
+A unique key for each class in the `Expression` hierarchy. This is useful for hashing and representing expressions as strings.
+
+#### args
+
+A dictionary used for mapping child arg keys, to the corresponding expressions. A value in this mapping is usually either a single or a list of `Expression` instances, but SQLGlot doesn't impose any constraints on the actual type of the value.
+
+#### arg_types
+
+A dictionary used for mapping arg keys to booleans that determine whether the corresponding expressions are optional or not. Consider the following example:
+
+```python
+class Limit(Expression):
+ arg_types = {"this": False, "expression": True}
+
+```
+
+Here, `Limit` declares that it expects to have one optional and one required child expression, which can be referenced through `this` and `expression`, respectively. The arg keys are generally arbitrary, but there are helper methods for keys like `this`, `expression` and `expressions` that abstract away dictionary lookups and related checks. For this reason, these keys are common throughout SQLGlot's codebase.
+
+#### parent
+
+A reference to the parent expression (may be `None`).
+
+#### arg_key
+
+The arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
+
+#### comments
+
+A list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
+
+#### type
+
+The data type of an expression, as inferred by SQLGlot's optimizer.