Exandra

https://hexdocs.pm/exandra/v1.0.0
Admin
Exandra is an Ecto adapter for Apache Cassandra and ScyllaDB that enables database interfacing,...
Tokens:3,427
Snippets:34
Trust Score:9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Execute UDT Operations in Migration

Source: https://hexdocs.pm/exandra

Use Ecto.Migration.execute/1 or execute/2 for UDT operations not supported by Ecto.Migration. This example creates a 'full_name' UDT.

```elixir
def change do
  execute(
    _up_query = "CREATE TYPE full_name (first_name text, last_name text))",
    _down_query = "DROP TYPE full_name"
  )
end
```

--------------------------------

### Define a Migration with a Table

Source: https://hexdocs.pm/exandra

Use Ecto.Migration to define table structures. This example creates a 'users' table with 'email' as the primary key and an 'age' field.

```elixir
defmodule AddUsers do
  use Ecto.Migration

  def change do
    create table("users", primary_key: false) do
      add :email, :string, primary_key: true
      add :age, :int
    end
  end
end
```

--------------------------------

### Execute a Batch Query

Source: https://hexdocs.pm/exandra

Execute multiple queries in a single request using Exandra.execute_batch/3. This example inserts two users into the 'users' table.

```elixir
queries = [
  {"INSERT INTO users (email) VALUES (?), ["jeff@example.com"},
  {"INSERT INTO users (email) VALUES (?), ["britta@example.com"]}
]

Exandra.execute_batch(MyApp.Repo, %Exandra.Batch{queries: queries})
```

--------------------------------

### Stream Query Results

Source: https://hexdocs.pm/exandra

Stream results of a simple or prepared query using Exandra.stream!/3. This example selects users who can be contacted and sends them an email.

```elixir
stream =
  Exandra.stream!(
    "SELECT * FROM USERS WHERE can_contact = ?",
    [true],
    MyRepo,
  )

Enum.each(
  stream,
  fn page ->
    Enum.each(page, fn user -> send_email(user.email, "Hello!") end)
  end
)
```

--------------------------------

### Define User Schema with Exandra

Source: https://hexdocs.pm/exandra

Example of defining an Ecto schema for Exandra, including a primary key and fields with standard and custom Exandra types like Exandra.Map.

```elixir
defmodule User do
  use Ecto.Schema

  @primary_key {:id, Ecto.UUID, autogenerate: true}
  schema "users" do
    field :email, :string
    field :meta, Exandra.Map, key: :string, value: :string
  end
end
```

--------------------------------

### Update a Counter Field

Source: https://hexdocs.pm/exandra

Update counter fields using Ecto.Repo.update_all/2. This example updates the 'total' counter for a specific route in the 'page_views' table.

```elixir
query =
  from page_view in "page_views",
    where: page_view.route == "/browse",
    update: [set: [total: 1]]

MyApp.Repo.update_all(query)
```

--------------------------------

### Configure Ecto.Repo with Exandra Adapter

Source: https://hexdocs.pm/exandra

Define your Ecto.Repo module to use Exandra as its adapter. Ensure the otp_app matches your application's name.

```elixir
defmodule MyApp.Repo do
  use Ecto.Repo, otp_app: :my_app, adapter: Exandra
end
```

--------------------------------

### Multiple Keyspaces using Prefixes

Source: https://hexdocs.pm/exandra

Query different keyspaces using the same schemas by employing query prefixes. Migrations must be run for each prefix.

```APIDOC
## Multiple Keyspaces using Prefixes

You can use query prefixes to query different keyspaces using the same schemas. As pointed out in the Ecto docs, migrations must be run for _each_ prefix in this case.
```

--------------------------------

### Migrations

Source: https://hexdocs.pm/exandra

Exandra supports migrations, including DDL-related commands from `Ecto.Migration`. It also provides guidance on Cassandra/Scylla types and User-Defined Types (UDTs).

```APIDOC
## Migrations

You can use Exandra to run migrations as well, as it supports most of the DDL-related commands from `Ecto.Migration`. For example:
```elixir
defmodule AddUsers do
  use Ecto.Migration

  def change do
    create table("users", primary_key: false) do
      add :email, :string, primary_key: true
      add :age, :int
    end
  end
end
```

#### Cassandra and Scylla Types
When writing migrations, remember that you must use the **actual types** from Cassandra or Scylla, which you must pass in as an _atom_.
For example, to add a column with the type of a map of integer keys to boolean values, you need to declare its type as `:"map<int, boolean>"`.
This is a non-comprehensive list of types you can use:
  * `:"map<key_type, value_type>"` - maps (such as `:"map<int, boolean>"`).
  * `:"list<type>"` - lists (such as `:"list<uuid>"`).
  * `:string` - gets translated to the `text` type.
  * `:map` - maps get stored as text, and Exandra dumps and loads them automatically.
  * `<udt>` - User-Defined Types (UDTs) should be specified as their name, expressed as an atom. For example, a UDT called `full_name` would be specified as the type `:full_name`.
  * `:naive_datetime`, `:naive_datetime_usec`, `:utc_datetime`, `:utc_datetime_usec` - these are all represented as the `timestamp` type.

### User-Defined Types (UDTs)
`Ecto.Migration` doesn't support creating, altering, or dropping Cassandra/Scylla **UDTs**. To do those operations in a migration, use `Ecto.Migration.execute/1` or `Ecto.Migration.execute/2`. For example, in your migration module:
```elixir
def change do
  execute(
    _up_query = "CREATE TYPE full_name (first_name text, last_name text))",
    _down_query = "DROP TYPE full_name"
  )
end
```
```

--------------------------------

### Exandra Database Connection Configuration

Source: https://hexdocs.pm/exandra

Configure database connection details for Exandra in your config/dev.exs file. This includes nodes, keyspace, connection timeouts, and logging levels.

```elixir
# Configure your database
config :my_app, MyApp.Repo,
  migration_primary_key: [name: :id, type: :uuid], # Overrides the default type `bigserial` used for version attribute in schema migration
  nodes: ["127.0.0.1"],  # List of database connection endpoints
  keyspace: "my_app_dev", # Name of your keyspace
  sync_connect: 5000,             # Waiting time in milliseconds for the database connection
  log: :info,
  stacktrace: true,
  show_sensitive_data_on_connection_error: true,
  pool_size: 10
```

--------------------------------

### Batch Queries

Source: https://hexdocs.pm/exandra

Exandra supports batch queries for Cassandra/Scylla, allowing multiple queries in a single request.

```APIDOC
## Batch Queries

You can run **batch queries** through Exandra. Batch queries are supported by Cassandra/Scylla, and allow you to run multiple queries in a single request. See `Exandra.Batch` for more information and examples.
```

--------------------------------

### Exandra Native Collections

Source: https://hexdocs.pm/exandra

Define fields for native Cassandra/Scylla collections like lists, maps, and sets using Elixir's tuple syntax or Exandra-specific types.

```elixir
@primary_key false
schema "hotels" do
  field :checkins, {:array, :utc_datetime}                            # list<timestamp>
  field :room_to_customer, Exandra.Map, key: :integer, value: :string # map<int, string>
  field :available_rooms, Exandra.Set, type: :integer                 # set<int>
end
```

--------------------------------

### stream!/3

Source: https://hexdocs.pm/exandra

Streams the results of a simple or prepared query.

```APIDOC
# stream!(repo, sql, values, opts \\ [])

```elixir
@spec stream!(Ecto.Repo.t(), String.t(), [term()], Keyword.t()) ::
  Xandra.PageStream.t()
```

Streams the results of a simple query or a prepared query.
See `Xandra.prepare!/4` and `Xandra.stream_pages!/4` for more information including supported options.
## Examples
```elixir
stream =
  Exandra.stream!(
    "SELECT * FROM USERS WHERE can_contact = ?",
    [true],
    MyRepo,
  )

Enum.each(
  stream,
  fn page ->
    Enum.each(page, fn user -> send_email(user.email, "Hello!") end)
  end
)
```
```

--------------------------------

### Exandra User-Defined Type (UDT) Declaration

Source: https://hexdocs.pm/exandra

Declare fields using Exandra.UDT for User-Defined Types in Cassandra/Scylla. The `type` option must match the UDT name in the database.

```elixir
field :home_phone, Exandra.UDT, type: :phone_number
field :office_phone, Exandra.UDT, type: :phone_number
```

--------------------------------

### execute_batch/3

Source: https://hexdocs.pm/exandra

Executes a batch query, which allows running multiple queries in a single request.

```APIDOC
# execute_batch(repo, batch, options \\ [])

```elixir
@spec execute_batch(Ecto.Repo.t(), Exandra.Batch.t(), keyword()) ::
  :ok | {:error, Exception.t()}
```

Executes a **batch query**.
See `Exandra.Batch`.
## Examples
```elixir
queries = [
  {"INSERT INTO users (email) VALUES (?)", ["jeff@example.com"]},
  {"INSERT INTO users (email) VALUES (?)", ["britta@example.com"]}
]

Exandra.execute_batch(MyApp.Repo, %Exandra.Batch{queries: queries})
```
```

--------------------------------

### Counter Tables

Source: https://hexdocs.pm/exandra

Exandra supports counter fields in counter tables. These fields can only be updated using `Ecto.Repo.update_all/2`.

```APIDOC
## Counter Tables

You can use the `Exandra.Counter` type to create counter fields (in counter tables). For example:
```elixir
@primary_key false
schema "page_views" do
  field :route, :string, primary_key: true
  field :total, Exandra.Counter
end
```

You can only _update_ counter fields. You'll have to use `c:Ecto.Repo.update_all/2` to insert or update counters. For example, in the table above, you'd update the `:total` counter field with:
```elixir
query =
  from page_view in "page_views",
    where: page_view.route == "/browse",
    update: [set: [total: 1]]

MyApp.Repo.update_all(query)
```
```

--------------------------------

### Define a Counter Table Schema

Source: https://hexdocs.pm/exandra

Use Exandra.Counter to create counter fields in counter tables. This schema defines a 'page_views' table with a 'route' primary key and a 'total' counter.

```elixir
@primary_key false
schema "page_views" do
  field :route, :string, primary_key: true
  field :total, Exandra.Counter
end
```

--------------------------------

### Exandra Inet Field Type

Source: https://hexdocs.pm/exandra

Use the Exandra.Inet type to represent Cassandra/Scylla's native `inet` type for IPv4 or IPv6 addresses.

```elixir
field :last_ip, Exandra.Inet
```

--------------------------------

### Exandra Composite Collections

Source: https://hexdocs.pm/exandra

Create composite collections in Exandra by nesting collection types. Note that typing information is applied at the same level for all collections.

```elixir
field :complex_type, {:array, Exandra.Map}, key: :string, value: Exandra.Set, type: :integer
```

```elixir
field :valid, Exandra.Set, type: Exandra.Set, type: :integer                                     # set<set<int>>
```

```elixir
field :invalid, Exandra.Map, key: Exandra.Set, type: :integer, value: Exandra.Set, type: :string # map<set<int>, set<int>> not map<set<int>, set<string>>
```

--------------------------------

### Exandra EmbeddedType for Ecto.Schema-backed UDTs

Source: https://hexdocs.pm/exandra

Use Exandra.EmbeddedType for UDTs backed by Ecto.Schema. Specify the `using` option with the schema module. For collections of UDTs, use `cardinality: :many`.

```elixir
field :home_phone, Exandra.EmbeddedType, using: MyApp.PhoneSchema
```

```elixir
field :home_phone, Exandra.EmbeddedType, cardinality: :many, using: MyApp.PhoneSchema
```

--------------------------------

### Exandra Tuple Field Type

Source: https://hexdocs.pm/exandra

Declare tuple fields using Exandra.Tuple, specifying the types of its elements in the `types` option.

```elixir
field :version, Exandra.Tuple, types: [:integer, :integer, :integer]
```

--------------------------------

### Exandra Map Field Type

Source: https://hexdocs.pm/exandra

Using the `:map` type in Exandra schemas. Data is stored as JSON blobs in the database. Be mindful of atom keys becoming strings upon retrieval.

```elixir
field :features, :map
```
Tokens:
Raw