README.md

# Triton

Pure Elixir Cassandra ORM built on top of Xandra.

[Blog Post](https://blog.sleeperbot.com/triton-a-cassandra-orm-for-elixir-882dd8f11383)

## Add Triton to your deps

Add triton to your deps.

```elixir
def deps() do
  [{:triton, "~> 0.2"}]
end
```

## Configure Triton

Single Cluster

```elixir
config :triton,
  clusters: [
    [
      conn: Triton.Conn,
      nodes: ["127.0.0.1"],
      pool: Xandra.Cluster,
      underlying_pool: DBConnection.Poolboy,
      pool_size: 10,
      keyspace: "my_keyspace",
      health_check_delay: 2500,  # optional: (default is 5000)
      health_check_interval: 500  # optional: (default is 1000)
    ]
  ]
```

Multi-Cluster

```elixir
config :triton,
  clusters: [
    [
      conn: Cluster1.Conn,
      nodes: ["127.0.0.1"],
      pool: Xandra.Cluster,
      underlying_pool: DBConnection.Poolboy,
      pool_size: 10,
      keyspace: "cluster_1_keyspace",
      health_check_delay: 2500,  # optional: (default is 5000)
      health_check_interval: 500  # optional: (default is 1000)
    ],
    [
      conn: Cluster2.Conn,
      nodes: ["127.0.0.1"],
      pool: Xandra.Cluster,
      underlying_pool: DBConnection.Poolboy,
      pool_size: 10,
      keyspace: "cluster_2_keyspace",
      health_check_delay: 2500,  # optional: (default is 5000)
      health_check_interval: 500  # optional: (default is 1000)
    ]
  ]
```

## Health Check

If DB gets disconnected, resulting in a DBConnection error, Triton will attempt to reconnect.

You can specify the **health_check_delay** and **health_check_interval** via the config for each cluster.

## Defining a Keyspace

First, define your keyspace.  Triton will create the keyspace for your at compile time if it does not exist.

```elixir
defmodule Schema.Keyspace do
  use Triton.Keyspace

  keyspace :my_keyspace, conn: Triton.Conn do
    with_options [
      replication: "{'class' : 'SimpleStrategy', 'replication_factor': 3}"
    ]
  end
end
```

## Defining a Table

You can define as many tables as you want.  Triton will create tables for you if they do not exist.

If you would like Triton to auto-create tables for you at compile time, you must require your Keyspace module.

```elixir
defmodule Schema.User do
  require Schema.Keyspace  
  use Triton.Table

  table :users, keyspace: Schema.Keyspace do
    field :user_id, :bigint, validators: [presence: true]  # validators using vex
    field :username, :text
    field :display_name, :text
    field :password, :text
    field :email, :text
    field :phone, :text
    field :notifications, {:map, "<text, text>"}
    field :friends, {:set, "<text>"}
    field :posts, {:list, "<text>"}
    field :updated, :timestamp
    field :created, :timestamp, transform: &Schema.Helper.DateHelper.to_ms/1  # transform field data
    partition_key [:user_id]
  end
end
```

## Defining a Materialized View

An example of a materialized view **users_by_email** with fields **user_id**, **email**, **display_name**, **password**.

Also demonstrates adding options like gc_grace_seconds and clustering_order_by.

```elixir
defmodule Schema.UserByEmail do
  require Schema.User  # if you want to auto-create at compile time
  use Triton.MaterializedView

  materialized_view :users_by_email, from: Schema.User do
    fields [
      :user_id,
      :email,
      :display_name,
      :password
    ]
    partition_key [:email]
    cluster_columns [:user_id]
    with_options [
      gc_grace_seconds: 172_800,
      clustering_order_by: [
        email: :asc,
        user_id: :desc
      ]
    ]
  end
end
```

An example of materialized view **users_by_email** with all fields

```elixir
defmodule Schema.UserByEmail do
  require Schema.User  
  use Triton.MaterializedView

  materialized_view :users_by_email, from: Schema.User do
    fields :all
    partition_key [:email]
    cluster_columns [:user_id]
  end
end
```

## Querying

First, import Triton.Query

```elixir
alias Schema.User
import Triton.Query
```

Select a single user where user_id = <id> using a prepared statement.

```elixir
User
|> prepared(user_id: id)
|> select([:user_id, :username])
|> where(user_id: :user_id)
|> User.one
```

Select users with IDs of 1, 2, or 3

```elixir
User
|> select([:user_id, :username])
|> where(user_id: [in: [1, 2, 3]])
|> limit(10)
|> allow_filtering  # you can allow filtering on any query
|> User.all
```

Select user with email **someone@gmail.com**

```elixir
UserByEmail
|> select([:display_name])
|> where(email: "someone@gmail.com")
|> User.one
```

## Comparison / Range Queries

Select messages created before **timestamp**

```elixir
MessagesByDate
|> select([:message_id, :text])
|> where(channel_id: 1, created: ["<=": timestamp])
|> limit(20)
|> MessagesByDate.all
```

Select messages created between **timestamp_a** and **timestamp_b**

```elixir
MessagesByDate
|> select([:message_id, :text])
|> where(channel_id: 1, created: [">=": timestamp_a], created: [<: timestamp_b])
|> MessagesByDate.all
```

## Streaming

Stream all messages

```elixir
MessagesByDate
|> select(:all)
|> where(channel_id: 1)
|> MessagesByDate.stream(page_size: 20)
```

Which returns {:ok, stream} or {:error, msg}

## Inserting, Updating, & Deleting

Again, lets import Triton.Query for the necessary macros.

```elixir
alias Schema.User
import Triton.Query
```

Add a user (if it doesn't already exist) with username **username** using a prepared statement that substitutes **user_id** into **:user_id**

```elixir
User
|> prepared(user_id: user_id, username: username)
|> insert(user_id: :user_id, username: :username)
|> if_not_exists
|> User.save
```

Update a user's username, and make sure to check that their previous username was what we expected.

```elixir
User
|> update(username: username)
|> where(user_id: user_id)
|> constrain(username: previous_username)
|> User.save
```

Lets delete a user given a **user_id**

```elixir
User
|> prepared(user_id: user_id)
|> delete(:all)  # here :all refers to all fields
|> where(user_id: :user_id)
|> User.del
```

Lets delete that same user, with consistency: :quorum

```elixir
User
|> prepared(user_id: user_id)
|> delete(:all)  # here :all refers to all fields
|> where(user_id: :user_id)
|> User.del(consistency: :quorum)
```

Batch update 4 users in 1 Cassandra request.

```elixir
[
  User |> update(username: "username1") |> where(user_id: 1),
  User |> update(username: "username2") |> where(user_id: 2),
  User |> update(username: "username3") |> where(user_id: 3),
  User |> update(username: "username4") |> where(user_id: 4)
] |> User.batch_execute
```

## Working with Collections

Update the **notifications** map to {'mentions': '3', 'replies': '3'}.  Overwrites the entire map.

```elixir
User
|> update(notifications: "{'mentions': '5', 'replies': '3'}")
|> where(user_id: 10)
|> User.save
```

Update notification mentions to '5'.

```elixir
User
|> update("notifications['mentions']": "5")
|> where(user_id: 10)
|> User.save
```

Update the friends set

```elixir
User
|> update(friends: "{'jill', 'bob', 'emma'}")
|> where(user_id: 10)
|> User.save
```

Add a friend_id to friends set

```elixir
User
|> update(friends: "friends + {'oscar'}")
|> where(user_id: 10)
|> User.save
```

Remove friend from set

```elixir
User
|> update(friends: "friends - {'oscar'}")
|> where(user_id: 10)
|> User.save
```

Update the posts list

```elixir
User
|> update(posts: "['post1', 'post2', 'post3']")
|> where(user_id: 10)
|> User.save
```

Append to posts list

```elixir
User
|> update(posts: "posts + ['post4']")
|> where(user_id: 10)
|> User.save
```

Prepend to posts list

```elixir
User
|> update(posts: "['post0'] + posts")
|> where(user_id: 10)
|> User.save
```

## Pre-populating data

You can pre-populate data with Triton at compile time with **Triton.Setup**

```elixir
defmodule PrepopulateModule do
  use Triton.Setup
  import Triton.Query
  require Schema.User
  alias Schema.User

  # create an admin user if it doesn't exist

  setup do
    User
    |> insert(
      user_id: @admin_user_id,
      username: @admin_user_username,
      display_name: @admin_user_display_name,
      password: Bcrypt.hashpwsalt(@admin_user_password),
      email: @admin_user_email,
      created: @admin_user_created
    ) |> if_not_exists
  end
end
```

## Automatic Schema Creation

Triton attempts to create your keyspace, tables, and materialized views at compile time if they do not exist.

This means that your build server will need access to your production DB if you want to automatically create your schema in prod.  The alternative is simply to create your production schemas yourself.

## Consistency levels

For dev, you may want to consider running ccm with more than 1 node if you are doing queries at anything more than consistency: :one.