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

Minor: Upate the sqllogictest crate README #7971

Merged
merged 4 commits into from
Oct 30, 2023
Merged

Minor: Upate the sqllogictest crate README #7971

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d6325a9
Minor: Upate the sqllogictest crate README
alamb Oct 29, 2023
6e7fdef
prettier
alamb Oct 29, 2023
78132d9
Apply suggestions from code review
alamb Oct 30, 2023
b0c4545
Merge remote-tracking branch 'apache/main' into alamb/sqllogictest_re…
alamb Oct 30, 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
37 changes: 22 additions & 15 deletions datafusion/sqllogictest/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,19 +17,26 @@
under the License.
-->

#### Overview
# DataFusion sqllogictest

This is the Datafusion implementation of [sqllogictest](https://www.sqlite.org/sqllogictest/doc/trunk/about.wiki). We
use [sqllogictest-rs](https://github.com/risinglightdb/sqllogictest-rs) as a parser/runner of `.slt` files
in [`test_files`](test_files).
[DataFusion](df) is an extensible query execution framework, written in Rust, that uses Apache Arrow as its in-memory format.
alamb marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
[DataFusion](df) is an extensible query execution framework, written in Rust, that uses Apache Arrow as its in-memory format.
\[DataFusion\](df) is an extensible query execution framework, written in Rust, that uses Apache Arrow as its in-memory format.


#### Testing setup
This crate is a submodule of DataFusion that contains an implementation of [sqllogictest](https://www.sqlite.org/sqllogictest/doc/trunk/about.wiki).

[df]: https://crates.io/crates/datafusion

## Overview

This crate uses [sqllogictest-rs](https://github.com/risinglightdb/sqllogictest-rs) to parse and run `.slt` files in the
[`test_files`](test_files) directory of this crate.

## Testing setup

1. `rustup update stable` DataFusion uses the latest stable release of rust
2. `git submodule init`
3. `git submodule update`

#### Running tests: TLDR Examples
## Running tests: TLDR Examples

```shell
# Run all tests
Expand All @@ -56,7 +63,7 @@ cargo test --test sqllogictests -- ddl --complete
RUST_LOG=debug cargo test --test sqllogictests -- ddl
```

#### Cookbook: Adding Tests
## Cookbook: Adding Tests

1. Add queries

Expand Down Expand Up @@ -95,9 +102,9 @@ SELECT * from foo;

Assuming it looks good, check it in!

#### Reference
# Reference

#### Running tests: Validation Mode
## Running tests: Validation Mode

In this model, `sqllogictests` runs the statements and queries in a `.slt` file, comparing the expected output in the
alamb marked this conversation as resolved.
Show resolved Hide resolved
file to the output produced by that run.
Expand All @@ -115,7 +122,7 @@ sqllogictests also supports `cargo test` style substring matches on file names t
cargo test --test sqllogictests -- information
```

#### Running tests: Postgres compatibility
## Running tests: Postgres compatibility

Test files that start with prefix `pg_compat_` verify compatibility
with Postgres by running the same script files both with DataFusion and with Posgres
alamb marked this conversation as resolved.
Show resolved Hide resolved
Expand Down Expand Up @@ -145,7 +152,7 @@ docker run \
postgres
```

#### Running Tests: `tpch`
## Running Tests: `tpch`

Test files in `tpch` directory runs against the `TPCH` data set (SF =
0.1), which must be generated before running. You can use following
Expand All @@ -165,7 +172,7 @@ Then you need to add `INCLUDE_TPCH=true` to run tpch tests:
INCLUDE_TPCH=true cargo test --test sqllogictests
```

#### Updating tests: Completion Mode
## Updating tests: Completion Mode

In test script completion mode, `sqllogictests` reads a prototype script and runs the statements and queries against the
database engine. The output is a full script that is a copy of the prototype script with result inserted.
Expand All @@ -177,7 +184,7 @@ You can update the tests / generate expected output by passing the `--complete`
cargo test --test sqllogictests -- ddl --complete
```

#### Running tests: `scratchdir`
## Running tests: `scratchdir`

The DataFusion sqllogictest runner automatically creates a directory
named `test_files/scratch/<filename>`, creating it if needed and
Expand All @@ -190,7 +197,7 @@ Tests that need to write temporary files should write (only) to this
directory to ensure they do not interfere with others concurrently
running tests.

#### `.slt` file format
## `.slt` file format

[`sqllogictest`] was originally written for SQLite to verify the
correctness of SQL queries against the SQLite engine. The format is designed
Expand Down Expand Up @@ -247,7 +254,7 @@ query <type_string> <sort_mode>
> :warning: It is encouraged to either apply `order by`, or use `rowsort` for queries without explicit `order by`
> clauses.

##### Example
### Example

```sql
# group_by_distinct
Expand Down