Settings View Source ArangoX Ecto

ArangoXEcto is an all-in-one Arango database adapter for the Elixir Ecto package. It has full support for Graphing, Arango Search, Geo Functions, AQL Integration, amongst other features.

table-of-contents

Table of Contents

• ArangoX Ecto
  • Table of Contents
  • About The Project
    • Built With
  • Getting Started
    • Prerequisites
    • Installation
  • Usage
    • Static or Dynamic
    • Basic Usage
      • Repo Setup
      • Schema Setup
      • Migration Setup
    • Raw AQL queries
    • Graph Relations
      • Generation of Edge Modules
      • Graphing in Ecto
      • One-to-One relationships
      • How it works
      • Example
      • More information
    • Arango Search
    • Further Usage
  • Roadmap
  • Contributing
  • License
  • Contact
  • Acknowledgements

about-the-project

About The Project

After playing around with different packages that implemented ArangoDB in Elixir, I found that there wasn't a package that suited my needs. I needed ArangoDB to work with Ecto seamlessly but there was no up-to-date adapter for Ecto available. ArangoX Ecto uses the power of ArangoX to communicate with ArangoDB and Ecto for the API in Elixir. Ecto is integrated with many other packages and can now be used with ArangoDB thanks to this package.

From version 1.0.0 onward graph relationships work seamlessly in Ecto.

built-with

Built With

• Arangox

getting-started

Getting Started

To get the adapter integrated with your project, follow these simple steps.

prerequisites

Prerequisites

• Elixir 1.12.3+ / Erlang OTP 22.2+ (Others may versions may work but this is the oldest it is tested on)

installation

Installation

Add the following line to your mix dependencies to get started.

{:arangox_ecto, "~> 1.3"}

usage

Usage

To connect to the database you need to specify the config values like so:

config :my_app, MyApp.Repo,
  database: "my_db",
  endpoints: "http://1.2.3.4:8529"

Only database and endpoints are required but there are other available options can be found in the Arangox docs.

The database should be setup using

$ mix ecto.setup.arango

static-or-dynamic

Static or Dynamic

In addition to default config variables, the static boolean config option can be passed to force the use of migrations. By default the value is false and collections that don't exist will be created on insert and on query no error will be raised. If set to true, any collections that do not exist on insert or query will result in an error to be raised.

Whether dynamic (default) or static is chosen defends on the database design of the project. For a production setup where lots of control is required, it is recommended to have static set to true.

If using static in production is better why is dynamic the default? Dynamic mode is the default because it is easier for development and testing then after that point static mode can be turned on for production.

basic-usage

Basic Usage

Repo Setup

To use the adapter in your repo, make sure your repo uses the ArangoXEcto.Adapter module for the adapter.

defmodule MyApp.Repo do
  use Ecto.Repo,
    otp_app: :my_app,
    adapter: ArangoXEcto.Adapter
end

Schema Setup

Since ArangoDB uses a slightly different id system, your schema must use the ArangoXEcto.Schema instead of Ecto.Schema.

defmodule MyApp.Accounts.User do
    use ArangoXEcto.Schema
    import Ecto.Changeset

    schema "users" do
      field :first_name, :string
      field :last_name, :string

      timestamps()
    end

    @doc false
    def changeset(app, attrs) do
      app
      |> cast(attrs, [:first_name, :last_name])
      |> validate_required([:first_name, :last_name])
    end
end

The options/1 and indexes/1 options can be optionally called inside the schema to set options and indexes to be created in dynamic mode. These options will have no effect in static mode.

For example, if you wanted to use a uuid as the key type and create an index on the email the following can be used.

defmodule MyApp.Accounts.User do
    use ArangoXEcto.Schema
    import Ecto.Changeset

    options [
      keyOptions: %{type: :uuid}
    ]

    indexes [
      [fields: [:email]]
    ]

    schema "users" do
      field :email, :string

      timestamps()
    end

    @doc false
    def changeset(app, attrs) do
      app
      |> cast(attrs, [:first_name, :last_name])
      |> validate_required([:first_name, :last_name])
    end
end

Please refer to the Schema documentation for more information on the available options.

Migration Setup

Using migrations is only required in static mode

If in dynamic mode (default), the adapter will automatically create collections if they don't already exist but there are cases where you might need to use a static system and hence migrations are required. For example, if you needed to create indexes as well, the following would be used.

Refer to ArangoXEcto.Migration for more information on usage.

defmodule MyApp.Repo.Migrations.CreateUsers do
    use ArangoXEcto.Migration

    def up do
      create(collection(:users))

      create(index("users", [:email]))
    end

    def down do
      drop(collection(:users))
    end
end

raw-aql-queries

Raw AQL queries

A lot of the time it is far more efficient to just run a raw AQL query, there's a function for that.

ArangoXEcto.aql_query(
    Repo,
    "FOR var in users FILTER var.first_name == @fname AND var.last_name == @lname RETURN var",
    fname: "John",
    lname: "Smith"
  )

This query will return a result such as:

{:ok,
    [
        %{
          "_id" => "users/12345",
          "_key" => "12345",
          "_rev" => "_bHZ8PAK---",
          "first_name" => "John",
          "last_name" => "Smith"
        }
    ]}

This is awesome functionality, but a lot of the time we will want to resemble a specific struct. This is actually quite easy with the help of the ArangoXEcto.load/2 function. The same query above could be extended to also convert the output:

ArangoXEcto.aql_query(
    Repo,
    "FOR var in users FILTER var.first_name == @fname AND var.last_name == @lname RETURN var",
    fname: "John",
    lname: "Smith"
  )
  |> case do
      {:ok, results} ->
        results
        |> ArangoXEcto.load(User)

      {:error, _reason} -> []
  end

This will return something like:

[
    %User{
      id: "12345",
      first_name: "John",
      last_name: "Smith"
    }
]

This is clearly a much better representation of the result and can be used in further Ecto methods.

graph-relations

Graph Relations

The adapter will dynamically create and manage edge collections. Each edge collection will be created as an Ecto schema when they are first used. This will allow for more extensibility through Ecto onto the edges.

Generation of Edge Modules

The module will be created under the closest common parent module of the passed modules plus the Edges alias. The order of the edge name will always be alphabetical to prevent duplicate edges. For example, if the modules were MyApp.Apple.User and MyApp.Apple.Banana.Post then the edge would be created at MyApp.Apple.Edges.PostsUsers. This assumes that the edge collection name was generated and not explicitly defined, if it was PostsUsers would be replaced with the camel case of that collection name (i.e. posts_users).

Graphing in Ecto

From version 1.0.0 onwards, edges are represented as traditional relationships in Ecto. This approach allows for the simplicity of simple management of edges but the complex querying through AQL.

The relationships are represented by an outgoing/3 and incoming/3 in the respective schemas. For example if you wanted to create edges between A and B, with the direction A -> B then A would have outgoing/3 and B would have incoming/3. This directionality is simply for what is put in the _from and _to fields in the Arango edge collection, if you don't care about directionality, you don't have to worry as much about which schema has outgoing/3 and incoming/3.

One-to-One relationships

Additionally, one_outgoing/3 and one_incoming/3 can be used for one-to-one relationships. These do not actually create edges but just store the _id of the target in a field instead. The order of the outgoing & incoming in schemas does matter as a field will be created in the incoming schema.

One-to-Many relationships

Graph relationships are a good substitute for many-to-many relationships in a traditional relational database. One-to-Many relationships in ArangoDB will function exactly the same as in a relational database. Therefore you can just use the regular Ecto.Schema.has_many/3 and Echo.Schema.belongs_to/3 functions as documented in the Ecto docs.

How it works

Behind the scenes these outgoing & incoming helper macros are simply wrappers around the Ecto function Ecto.Schema.many_to_many/3. The one-to-one outgoing & incoming macros are just wrappers around Ecto.Schema.has_one/3 and Ecto.Schema.belongs_to/3 respectively. Hence once setup the regular methods for handling Ecto relationships can be used.

In order to delete a specific edge, you can do it exactly as you would any other Ecto struct (since after all it is one) or Ecto relation.

Querying of edges can be done either through using an AQL query or by using Ecto methods.

Example

Let's say you wanted to create an edge between your Post and User schema. You could implement it as follows:

defmodule MyProject.User do
  use ArangoXEcto.Schema

  schema "users" do
    field :name, :string

    # Will use the automatically generated edge
    outgoing :posts, MyProject.Post

    # Or use the UserPosts edge
    # outgoing :posts, MyProject.Post, edge: MyProject.UserPosts
  end
end

defmodule MyProject.Post do
  use ArangoXEcto.Schema

  schema "posts" do
    field :title, :string

    # Will use the automatically generated edge
    incoming :users, MyProject.User

    # Or use the UserPosts edge
    # incoming :users, MyProject.User, edge: MyProject.UserPosts
  end
end

More information

To learn about using the schema functions for representing graph relationships and examples, read the docs at ArangoXEcto.Schema.

To read more about Edge Schemas and how to extend edge schemas to add additional fields, read the docs on ArangoXEcto.Edge.

To learn how to use the helper functions (as well as other useful methods) check out the full documentation.

arango-search

Arango Search

As of version 1.3.0 Arango Search functionality is built in. This builds off of the Ecto schema module for views so they can be searched and interacted with like regular collections. The view schemas are not exactly the same as collection or edge schemas because the views don't actually store or hold any data and aren't structs themselves. Views act as alias interfaces that over the collections and edge schemas.

Querying

Querying views works exactly the same as querying a regular collection or edge schema. For example, the following will work as you would expect.

# Module definition
defmodule UsersView do
  use ArangoXEcto.View

  alias ArangoXEcto.View.Link

  view "user_search" do
    primary_sort(:created_at, :asc)

    store_value([:first_name], :lz4)

    link(User, %Link{
      includeAllFields: true,
      fields: %{
        last_name: %Link{
          analyzers: [:text_en]
        }
      }
    })

    options(primarySortCompression: :lz4)
  end
end

# Querying
iex> Repo.all(UsersView)
[%User{first_name: "John", last_name: "Smith"}, _]

In addition to regular querying ArangoDB has the AQL SEARCH function for performing searches on views. This is implemented in ArangoXEcto using an additional Ecto query macro. The search/3 and or_search/3 macros are provided to utalise this functionality. Details of how to use these functions can be found in ArangoXEcto.Query and the ArangoXEcto.View modules.

Behind the scenes the search/3 and or_search/3 are just wrappers around the Ecto where clause that gets unwrapped at the point when the AQL query is generated.

Analyzers

Analyzers can also be defined from within an analyzer module. Refer to the ArangoXEcto.Analyzer module for documentation.

further-usage

Further Usage

For more examples and full documentation, please refer to the Documentation.

roadmap

Roadmap

See the the roadmap for a list of proposed features (and known issues) planned.

contributing

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

Checkout the Contributing Guide.

license

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

contact

Contact

Project Home: https://github.com/TomGrozev/arangox_ecto

acknowledgements

Acknowledgements

• mpoeter - Wrote the original Ecto Query to AQL code
• kianmeng - README changes & CI dep change
• bodbdigr - Fixed AQL query typespec
• hengestone - Added option to use different migrations directory