Metadata-Version: 2.4
Name: querre
Version: 0.0.1
Summary: SQL-like CSV data query tool
Author: Shinichiro Ikeda
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pegase

# Querre
SQL-like CSV data query tool


## Overview
Querre is a command-line tool that allows you to search data provided in CSV files using an SQL-like query language. Its query language features syntax equivalent to the SQL `SELECT` statement; it treats CSV files as tables to perform searches and outputs the results in CSV format to standard output.


### CSV file to be queried
The data to be queried is provided as a CSV file. In Querre's query language, you can treat the contents of a CSV file like a table by specifying the CSV filename where you would normally specify a table name in SQL.
When loading CSV file data into Querre and handling it as a table, it is necessary to determine how to interpret column names and data types. This affects not only the loading of the CSV file but also the display of query results.
Here, we explain how Querre handles each of the following items.
You may wish to adjust these settings individually depending on the type of CSV file being processed. To accommodate this, Querre allows you to modify the default behavior via the command line and specify file-specific behavior (such as how the file is read) when designating a CSV file within the query syntax.

### Specifying column names
When reading a CSV file, the first line is treated as a header row, and the values ​​in those columns are used as column names.
It is not possible to specify the presence of a header or the column names via the command line.
When specifying a CSV file in the query syntax, you can use the `WITH/WITHOUT HEADER (column_name,...)` clause to specify the presence or absence of a header row and define the column names on a per-file basis.

### String quotation marks
String values ​​in CSV file columns are assumed to be enclosed in quotation marks and are read with the surrounding quotes removed.
If the `--unquoted_string` command-line argument is specified, the strings are treated as unquoted and read exactly as they appear in the file.
You can specify whether quotation marks are present on a per-file basis by designating `QUOTED STRING` or `UNQUOTED STRING` when specifying the CSV file in the query syntax.

### Handling Numeric Strings
If a column in a CSV file contains a string representing a numeric value, that string is converted to a number upon import.
If the `--digits_as_string` command-line argument is specified, strings representing numeric values ​​are imported as strings.
You can specify how numeric strings are handled on a per-file basis by including `DIGITS AS STRING` or `DIGITS AS NUMERIC` when specifying the CSV file in the query syntax.

### Handling Date Strings
Even if a column in a CSV file contains a string representing a date, it is normally read simply as a string.
If the `--datetime_format` command-line argument is specified, the system attempts to convert the column string into a `datetime` object using Python's `strptime()` with the format provided in the argument; if successful, it is read as a `datetime` object, whereas if conversion fails, it is read as a string.
By specifying `DATE_FORMAT` when designating a CSV file in the query syntax, you can define the date conversion format on a per-file basis.

### Handling of NULL strings
If a column in a CSV file contains the string "NULL", it is read as NULL (a value representing an "unknown value" or "absence of value").
If the `--null_literal` command-line argument is specified, a column's string is read as NULL if it matches the specified string.
By specifying `NULL_LITERAL` when designating a CSV file in the query syntax, you can specify the string representing NULL on a per-file basis.

## Command line
Querre is implemented as a Python package, with a CLI interface that allows it to be executed as a command from a UNIX shell.
Two execution methods are provided for running queries: specifying the query syntax directly as a command-line argument, or specifying a file that contains the query syntax.

```
$ python -m querre [-c 'query syntax'] [-f query-file] [--unquoted_string] [--digits_as_string] [--datetime_format '%Y-%m-%d'] [--null_literal NULL]
```

Specify the query to be executed using the -c 'query syntax' modifier or the -f query_file_name option.


## Query language
Querre's query language is designed to resemble the SQL SELECT statement.
The query syntax is modeled after the standard SQL SELECT statement to ensure similar behavior. While the basic syntax is based on the SQL-92 SELECT statement, it incorporates the WITH clause syntax from SQL:1999, window function syntax from SQL:2003, and a few additional constructs not defined in standard SQL.
Although it borrows heavily from standard SQL syntax, it is not fully compliant with the standard.

In the development of Querre, we first implement a query syntax with basic functionality targeting a single file, and subsequently extend it to include features such as grouping, multi-table joins, window functions, and WITH clauses.
The query syntax to be implemented in the initial version of Querre is shown below.

```
SELECT
    column_name
FROM
    CSV_file_name
WHERE
    search_condition
ORDER BY
    output_order_specification
```

