Registry / aws / py-partiql-parser

py-partiql-parser

library0.6.3pypypi✓ verified 27d ago

py-partiql-parser is a pure Python tokenizer, parser, and executor for the PartiQL language. PartiQL is an expressive, SQL-compatible query language for relational, semi-structured, and nested data, primarily maintained by Amazon. The library is currently at version 0.6.3 and appears to be actively maintained, with releases indicating ongoing development, though without a fixed cadence.

aws database data

pip install py-partiql-parser

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · PY-PARTIQL-PARSER

py-partiql-parser

awspythonv0.6.3

Install

1.6s avg

Import

28ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.030s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.026s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DynamoDBStatementParser

✓ from py_partiql_parser import DynamoDBStatementParser

This example demonstrates how to parse a PartiQL statement into an Abstract Syntax Tree (AST) and then execute it against an in-memory Python list of dictionaries using the built-in executor.

from py_partiql_parser import DynamoDBStatementParser # Instantiate the parser parser = DynamoDBStatementParser() # PartiQL statement to parse statement = "select * from my_table where id = '123'" # Parse the statement to get the Abstract Syntax Tree (AST) parsed_ast = parser.parse(statement) print(f"Parsed AST: {parsed_ast}") # You can also execute the parsed statement with an in-memory dataset data = [{"id": "123", "name": "foo"}, {"id": "456", "name": "bar"}] result = parsed_ast.execute(data) print(f"Execution result: {result}")

Debug

Known issues

gotchaThe project is described as 'Much beta, such wow' on PyPI. This suggests the library is still under active development and may have evolving APIs or unaddressed edge cases. Users should be mindful of potential changes in future minor versions.

fix

Refer to the project's GitHub repository for the latest documentation and changelog. Test thoroughly when upgrading.

affects: 0.1.0-0.6.x

gotchaThe library explicitly notes that AWS's native PartiQL implementation (e.g., in DynamoDB) does not fully follow the PartiQL spec, specifically regarding querying lists of JSON documents (e.g., `SELECT *` vs. `SELECT key` for each document) and lacking `SELECT VALUES`. The parser's behavior might therefore differ from AWS's actual runtime.

fix

Consult both the `py-partiql-parser` documentation and AWS's official PartiQL documentation for DynamoDB to understand potential dialect differences if targeting AWS services.

affects: All versions

gotchaThis library is a *pure Python parser and in-memory executor* of PartiQL. It does *not* directly integrate with `boto3` or AWS services for executing queries against live DynamoDB tables. Users aiming to query live DynamoDB via Python should typically use `boto3`'s `execute_statement` API directly with the PartiQL string. This library is best for parsing, validating, or executing PartiQL against local data structures.

fix

For live AWS DynamoDB queries, use `boto3.client('dynamodb').execute_statement(Statement='...')`. Use `py-partiql-parser` for local PartiQL AST manipulation or in-memory execution.

affects: All versions

gotchaA common point of confusion for users of PartiQL with DynamoDB is that DynamoDB's native PartiQL dialect does not support `AS` aliases in `SELECT` clauses, unlike standard SQL. If `py-partiql-parser` supports `AS` in its parsing, the resulting PartiQL string (if re-serialized) or logical intent might not be directly compatible with AWS DynamoDB.

fix

When writing PartiQL for DynamoDB, avoid `AS` aliases in `SELECT` statements. If this parser generates an AST with aliases, consider how that AST will be used downstream, especially if it's meant for AWS services.

affects: All versions

gotchaThe `DynamoDBStatementParser` class requires a `source_data` argument during instantiation. Attempting to instantiate it without this argument will result in a `TypeError`. This is a common point of confusion for new users expecting a default or no-argument constructor.

fix

Ensure `DynamoDBStatementParser` is instantiated with the `source_data` argument, providing the PartiQL string to be parsed, e.g., `parser = DynamoDBStatementParser(source_data='SELECT * FROM my_table')`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'py_partiql_parser'

The `py-partiql-parser` library is not installed in the Python environment, or there's a typo in the import statement.

fix

Install the library using pip: `pip install py-partiql-parser` or ensure the import statement is correct, e.g., `from py_partiql_parser import PartiQLParser`.

Failed to parse query

The provided PartiQL query string contains a syntax error or is malformed according to the PartiQL specification.

fix

Review the PartiQL query for syntax errors, incorrect keywords, or improper structure. Consult the PartiQL specification or examples for correct syntax, especially for complex queries or nested data. For instance, ensure proper quoting for identifiers if they contain special characters or are reserved words.

ValidationException: Unexpected from source

When using PartiQL with AWS DynamoDB via `boto3`, this error often occurs if a table name containing special characters (like hyphens) or a reserved keyword is not enclosed in double quotes.

fix

Enclose the DynamoDB table name (and potentially attribute names) in double quotes within the PartiQL query string. For example, `SELECT * FROM "my-table" WHERE id = '123'` instead of `SELECT * FROM my-table WHERE id = '123'`.

AttributeError: 'PartiQLParser' object has no attribute 'parse'

This typically means that the object instantiated, or the way `parse` is called, is incorrect. It might be due to a wrong class being instantiated or attempting to call a method that doesn't exist or is not directly accessible. While 'parse' is a core method, this error can arise if a different parser class (e.g., S3SelectParser, DynamoDBStatementParser) is expected or if the library's API changed in a breaking way.

fix

Ensure you are importing and instantiating the correct parser class (e.g., `from py_partiql_parser import PartiQLParser` or `from py_partiql_parser import S3SelectParser` or `from py_partiql_parser import DynamoDBStatementParser`) and calling its `parse` method with the appropriate arguments. Check the library's documentation for the correct class and method signatures for your specific use case.

Upgrade

Version history

0.6.3latest on PyPI · released Oct 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/getmoto/py-partiql-parser ↗

packagehttps://pypi.org/project/py-partiql-parser/ ↗

changeloghttps://github.com/getmoto/py-partiql-parser/blob/main/CHANGELOG.md ↗