JSqlParser Documentation

What it does Copy Chapter

Give it SQL. Get an AST you can walk, rewrite, and print back out.

SELECT 1 FROM dual WHERE a = b

SQL Text
 └─Statements: statement.select.PlainSelect
    ├─selectItems: statement.select.SelectItem
    │  └─LongValue: 1
    ├─Table: dual
    └─where: expression.operators.relational.EqualsTo
       ├─Column: a
       └─Column: b

String sqlStr = "select 1 from dual where a=b";

PlainSelect select = (PlainSelect) CCJSqlParserUtil.parse(sqlStr);

SelectItem selectItem = select.getSelectItems().get(0);
Assertions.assertEquals(new LongValue(1), selectItem.getExpression());

Table table = (Table) select.getFromItem();
Assertions.assertEquals("dual", table.getName());

EqualsTo equalsTo = (EqualsTo) select.getWhere();
Column a = (Column) equalsTo.getLeftExpression();
Column b = (Column) equalsTo.getRightExpression();
Assertions.assertEquals("a", a.getColumnName());
Assertions.assertEquals("b", b.getColumnName());

The tree is traversable with the Visitor pattern, and the same object model works in reverse:
build statements from Java with a fluent API
and render them as SQL text.

Install Copy Chapter

Use the stable Manticore builds. They are released continuously from the current development
line and carry all of the performance and grammar work described below. The upstream
com.github.jsqlparser release on Maven Central is considerably older.

<dependency>
    <groupId>com.manticore-projects.jsqlformatter</groupId>
    <artifactId>jsqlparser</artifactId>
    <version>[5.3.218,)</version>
</dependency>

implementation("com.manticore-projects.jsqlformatter:jsqlparser:+")

Upstream release and snapshots

<dependency>
    <groupId>com.github.jsqlparser</groupId>
    <artifactId>jsqlparser</artifactId>
    <version>5.3</version>
</dependency>

Snapshot coordinates and repository setup are on the
build dependencies page.

Performance Copy Chapter

11× faster than 5.3, and the fastest parser on real-world SQL of any of the parsers
tested, in any language — 19× ahead of sqlglot[c] on JSqlParser's own SELECT test suite.

Benchmark                               (version)  Mode  Cnt   Score   Error  Units
JSQLParserBenchmark.parseSQLStatements     latest  avgt   15   7.602 ± 0.135  ms/op
JSQLParserBenchmark.parseSQLStatements        5.3  avgt   15  84.687 ± 3.321  ms/op

Methodology and the full cross-parser comparison against SQLGlot, sqlglot[c] and
polyglot-sql: jsqlparser-bench.

What it parses Copy Chapter

JSqlParser targets the SQL standard plus all major RDBMS. One grammar covers all of them,
and missing syntax gets added on demand — open an issue.

Beyond statement shapes, the grammar handles nested sub-selects, bind parameters (?,
:name), window and analytic functions, Oracle hints, and the T-SQL square-bracket versus
array-literal ambiguity. The complete reference is on the
syntax page.

Piped SQL Copy Chapter

Support is progressing for Piped SQL, which writes queries in the order they actually
execute rather than the order SQL historically demanded.

FROM Produce
|> WHERE
    item != 'bananas'
    AND category IN ('fruit', 'nut')
|> AGGREGATE COUNT(*) AS num_items, SUM(sales) AS total_sales
   GROUP BY item
|> ORDER BY item DESC;

Background reading: the Google research paper,
BigQuery pipe syntax
and DuckDB FROM-first syntax.

Java version Copy Chapter

Sister projects Copy Chapter

• JSQLFormatter — pretty-printing and formatting of SQL text
• JSQLTranspiler — dialect-specific rewriting, column resolution and lineage, by Starlake.ai

Alternatives Copy Chapter

The dual-licensed JOOQ
ships a hand-written parser with broad RDBMS support, cross-dialect translation, SQL
transformation, and a JDBC proxy mode. Worth a look if translation between dialects is your
primary need rather than AST access.

Sponsor Copy Chapter

A huge thank you to Starlake.ai, who simplify data ingestion,
transformation and orchestration for faster delivery of high-quality data. Starlake has been
instrumental in providing Piped SQL support and a large number of test cases for BigQuery,
Redshift, Databricks and DuckDB. If JSqlParser is useful to you, visit
Starlake.ai and give them a star.

Documentation Copy Chapter

1. Samples
2. Build instructions and Maven artifact
3. Contribution guide
4. Change log
5. Issues

License Copy Chapter

Dual licensed under LGPL 2.1 or the Apache License, Version 2.0. Take your pick.