From 2457c172ddf6cabf2f2d4b1166b8d6a046cb93d2 Mon Sep 17 00:00:00 2001 From: surister Date: Sat, 6 Jul 2024 18:10:55 +0200 Subject: [PATCH] Javascript: Update docs --- cratedb_sqlparse_js/README.md | 156 ++++++++++++++++-- .../cratedb_sqlparse/models.js | 3 +- cratedb_sqlparse_js/tests/enricher.test.js | 4 +- 3 files changed, 149 insertions(+), 14 deletions(-) diff --git a/cratedb_sqlparse_js/README.md b/cratedb_sqlparse_js/README.md index 6019bd6..1e1f73d 100644 --- a/cratedb_sqlparse_js/README.md +++ b/cratedb_sqlparse_js/README.md @@ -9,12 +9,12 @@ ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/@cratedb/cratedb-sqlparse) ![NPM Type Definitions](https://img.shields.io/npm/types/@cratedb/cratedb-sqlparse) - CrateDB SQL Parser for JavaScript, compiled from antlr4 JavaScript compile target. ### Simple usage + ```javascript -import { sqlparse } from "@cratedb/cratedb-sqlparse"; +import {sqlparse} from "@cratedb/cratedb-sqlparse"; const query = ` SELECT * FROM SYS.SHARDS; @@ -37,27 +37,161 @@ console.log(queries[0].original_query) ``` ### CrateDB version + You can programmatically check the CrateDB version the package was compiled for in `index.js` ```javascript -import { __cratedb_version__ } from "@cratedb/cratedb-sqlparse"; +import {__cratedb_version__} from "@cratedb/cratedb-sqlparse"; console.log(__cratedb_version__) -// 5.6.4 +// 5.7.2 ``` ### Features -Currently, we support the same features as CrateDB java's parser: + +Currently, we support some of the same features as CrateDB java's parser: + - First class CrateDB SQL dialect support. - Input is case-insensitive. -- Native errors as exceptions. +- Native errors as exceptions or as objects. - Dollar strings. +- Tables +- Properties and Parametrized properties. + +### Exceptions and errors. + +By default exceptions are stored in `statement.exception` -Optional features: +```javascript +import {sqlparse} from "@cratedb/cratedb-sqlparse"; -### Errors -Errors are thrown as 'ParseError' e.g. +const query = ` +SELECT COUNT(*) FROM doc.tbl f HERE f.id = 1; -```text -ParseError: line2:9 mismatched input 'ROM' expecting {, ';'} +INSERT INTO doc.tbl VALUES (1, 23, 4); +` +const statements = sqlparse(query) +const stmt = statements[0] + +if (stmt.exception) { + console.log(stmt.exception.errorMessage) + // [line 2:43 mismatched input 'HERE' expecting {, ';'}] + + console.log(stmt.exception.errorMessageVerbose) + // SELECT COUNT(*) FROM doc.tbl f HERE f.id = 1; + // ^^^^ + // INSERT INTO doc.tbl VALUES (1, 23, 4); +} ``` + +In some situations, you might want sqlparse to raise an exception. + +You can set `raise_exception` to `true` + +```javascript +import {sqlparse} from "@cratedb/cratedb-sqlparse"; + +let stmt = sqlparse('SELECT COUNT(*) FROM doc.tbl f WHERE .id = 1;', true); + +// throw new ParseError( +// ^ +// +// ParseError: no viable alternative at input 'SELECT COUNT(*) FROM doc.tbl f WHERE .' +``` + +Catch the exception: + +```javascript +import {sqlparse} from "@cratedb/cratedb-sqlparse"; + +try { + sqlparse('SELECT COUNT(*) FROM doc.tbl f WHERE .id = 1;', true) +} catch (e) { + console.log(e) +} +``` + +> [!NOTE] +> It will only raise the first exception it finds, even if you pass in several statements. + +### Query metadata. + +Query metadata can be read with `statement.metadata` + +```javascript +import {sqlparse} from "@cratedb/cratedb-sqlparse"; + +const stmt = sqlparse("SELECT A, B FROM doc.tbl12")[0] + +console.log(stmt.metadata); + +// Metadata { +// tables: [ Table { name: 'tbl12', schema: 'doc' } ], +// parameterizedProperties: {}, +// withProperties: {} +// } + +``` + +#### Query properties. + +Properties defined within a `WITH` statement, `statement.metadata.withProperties:`. + +```javascript +import {sqlparse} from "@cratedb/cratedb-sqlparse"; + + +const stmt = sqlparse(` + CREATE TABLE doc.tbl12 (A TEXT) WITH ( + "allocation.max_retries" = 5, + "blocks.metadata" = false + ); +`)[0] + +console.log(stmt.metadata); + +// Metadata { +// tables: [ Table { name: 'tbl12', schema: 'doc' } ], +// parameterizedProperties: {}, +// withProperties: { 'allocation.max_retries': '5', 'blocks.metadata': 'false' } +// } +``` + +#### Table name +```javascript +console.log(stmt.metadata.tables) +// [ Table { name: 'tbl12', schema: 'doc' } ] + +table = stmt.metadata.tables[0] + +console.log(table.schema, table.name, table.fqn) +// doc tbl12 "doc"."tbl12" +``` + +#### Parameterized properties. + +Parameterized properties are properties without a real defined value, marked with a dollar string, `metadata.parameterized_properties` + +```javascript +import {sqlparse} from "@cratedb/cratedb-sqlparse"; + +const stmt = sqlparse(` + CREATE TABLE doc.tbl12 (A TEXT) WITH ( + "allocation.max_retries" = 5, + "blocks.metadata" = $1 +); +`)[0] + +console.log(stmt.metadata) + +// Metadata { +// tables: [ Table { name: 'tbl12', schema: 'doc', fqn: '"doc"."tbl12"' } ], +// parameterizedProperties: { 'blocks.metadata': '$1' }, +// withProperties: { 'allocation.max_retries': '5', 'blocks.metadata': '$1' } +// } +``` + +In this case, `blocks.metadata` will be in `with_properties` and `parameterized_properties` as well. + +For values to be picked up they need to start with a dollar `'$'` and be preceded by integers, e.g. `'$1'` or `'$123'`. +`'$123abc'` would not be valid. \ No newline at end of file diff --git a/cratedb_sqlparse_js/cratedb_sqlparse/models.js b/cratedb_sqlparse_js/cratedb_sqlparse/models.js index a4555fa..237fb6b 100644 --- a/cratedb_sqlparse_js/cratedb_sqlparse/models.js +++ b/cratedb_sqlparse_js/cratedb_sqlparse/models.js @@ -39,12 +39,13 @@ export class Table { constructor(name, schema) { this.name = name this.schema = schema + this.fqn = this._getFqn() } /** * @return {String} The full qualified name, quoted. */ - getFqn() { + _getFqn() { return (this.schema ? quoted(this.schema) + "." : "") + quoted(this.name) } } \ No newline at end of file diff --git a/cratedb_sqlparse_js/tests/enricher.test.js b/cratedb_sqlparse_js/tests/enricher.test.js index 3a460f3..9b09e14 100644 --- a/cratedb_sqlparse_js/tests/enricher.test.js +++ b/cratedb_sqlparse_js/tests/enricher.test.js @@ -19,11 +19,11 @@ test("Statement's metadata has Tables", () => { expect(stmt.metadata.tables).not.toBeNull expect(stmt.metadata.tables[0].schema).toBe('a') expect(stmt.metadata.tables[0].name).toBe('b') - expect(stmt.metadata.tables[0].getFqn()).toBe('"a"."b"') + expect(stmt.metadata.tables[0].fqn).toBe('"a"."b"') expect(stmt.metadata.tables[1].schema).toBeNull() expect(stmt.metadata.tables[1].name).toBe('d') - expect(stmt.metadata.tables[1].getFqn()).toBe('"d"') + expect(stmt.metadata.tables[1].fqn).toBe('"d"') }) test("Statement's metadata correctly gets parameterized properties", ()=>{