# Welcome

Kye stands for “Know Your Edges”. It is intended to be a very simple language with punctuation similar to JSON.

It is similar in purpose to GraphQL where it tries to serve as an universal place for data models to be defined. When those data models are attached to an engine, the engine can validate whether or not given data matches the defined data models.

I also envision extraction and transformation functions to be attached to data models so that a Kye query can extract and serve the data as requested. Enabling a Kye platform to be a one-stop shop for managing all data across many sources.

```
User(id)(username) {
  id: Number
  username: String
  name: String
  age?: Number

  assert age > 0 & age <= 120
}
```


# Quick Start

## Install

Kye is available as a python library on [pypi](https://pypi.org/project/kye/)

```
pip install kye
```

## Run

Pass the location of the kye file, the data (`.csv`, `.json` or `.jsonl`) file, and the name of the Model to evaluate the data against. If the data does not pass the model's assertions then the errors and errant data will be displayed.

```
kye user.kye --data users.csv --model User
```

## Compile

The Kye language can optionally be compiled into a json or yaml file. Using the `-c` flag followed by a path to a `.json` or `.yaml` file. Run the compiled file like you would a normal `.kye` file

```
kye user.kye -c user.kye.yaml
kye user.kye.yaml --data users.csv --model User
```


# Defining Models

## Models

The below Kye script defines a `User` table. Table names must be uppercased.

```
User(id)(username) {
  id: Number
  username: String
  name: String
  age?: Number

  assert age > 0 & age <= 120
}
```

## **Indexes**

The name of the table is followed by its index definition. The `(id)(username)` means that we expect both the `id` or `username` columns to be able to uniquely identify a record.

Composite indexes are defined by listing multiple column names within a single set of parenthesis ex. `(id, username)`

## **Columns**

Column names must start with a lowercase and not contain spaces or other special characters. If the source data has column names that don't follow these rules, then you can specify the full column name in quotes after the column name.

```
  id "User Id": Number
```

The column definitions specify the value type as `Number`, `String` or `Boolean`. More data types like date/time and user defined types are coming soon.

You can specify whether the column allows null values by prefixing the colon with a `?`

```
age?: Number
```

You can also specify if the column allows multiple values (like an array of values) by using `+` if you expect at least one value, or `*` if it is okay to have no values.

```
# Expect at least one version
versions+: String

# It's okay for a post to have no tags
tags*: String 
```

## **Assertions**

You can specify extra assertions through the `assert` keyword. Just write an expression that evaluates to true or false, and the rows that evaluate to false will be flagged. You can reference columns by their names.


# Querying Models

Queries are expressions that are used in a variety of places; selecting & filtering models, defining edge types & assertions.

Expressions used in the global scope return tables. For example, the following commands will display different views of the `User` table

```
> User

> User[name == "Ben"]

> User{ id, name }
```

Expressions used within the scope of a table generate a column. For example, a filter expression, an assertion expression, or computed column expression.

<pre><code><strong>> User{ full_name: first_name + ' ' + last_name }
</strong></code></pre>

## Expressions

Expressions support the basic operations:

* `+ - * / %` math
* `== != >= > < <=` comparison
* `! & | ^` logical (not, and, or, xor)
* `()` parenthesis

## Selecting

Use the curly brackets after a table expression to create a new view of that type, showing only the listed columns, able to define new computed columns, or define additional assertions for that view.

```
> User {
    id,
    full_name: first_name + ' ' + last_name
    assert id > 0
  }
```

## Filtering

Use square brackets after a table expression with a list of expressions that all must be true in order to be included in the resulting table.

```
> User[
    name == "Ben"
    country == "US"
  ]
```