ExOdata4

An OData v4 query parser and Ecto query builder for Elixir. Parse OData query strings or full URIs and get back Ecto queries ready to execute against your own repo.

Installation

Add ex_odata4 to your dependencies in mix.exs:

def deps do
  [
    {:ex_odata4, "~> 0.1.0"}
  ]
end

Configuration

Tell the library which OData entity names map to your Ecto schemas in config/config.exs:

config :ex_odata4, schemas: %{
  "Orders" => MyApp.Orders,
  "Products" => MyApp.Products
}

The key is the entity name as it appears in the OData URI. The value is the Ecto schema module.

Usage

Parsing a full OData URI

ExOdata4.parse_uri("/Orders?$filter=Amount gt 1000&$top=25&$skip=0")
|> MyApp.Repo.all()

Parsing a query string directly

ExOdata4.get("Orders", "$filter=Status eq &#39;active&#39;&$orderby=CreatedAt desc&$top=10")
|> MyApp.Repo.all()

Both functions return an %Ecto.Query{}, so you pipe it into your own repo. This means the library has no opinion about your database, connection pool, or repo configuration.

Supported OData query options

Option	Example
`$filter`	`$filter=Name eq 'John'`
`$top`	`$top=25`
`$skip`	`$skip=50`
`$orderby`	`$orderby=Amount desc`

Supported filter operators

Operator	Meaning
`eq`	Equal
`ne`	Not equal
`gt`	Greater than
`ge`	Greater than or equal
`lt`	Less than
`le`	Less than or equal
`and`	Logical and
`or`	Logical or

Supported filter functions

Function	Example	Translates to
`contains`	`contains(Name, 'John')`	`LIKE '%John%'`
`startswith`	`startswith(Name, 'J')`	`LIKE 'J%'`
`endswith`	`endswith(Email, '.com')`	`LIKE '%.com'`

Functions can be combined with logical operators:

$filter=contains(Name, 'John') and Amount gt 100
$filter=startswith(Status, 'act') or endswith(Email, '.com')

Supported literal types

Strings: 'hello'
Integers: 42, -7
Decimals: 3.14
Booleans: true, false
Null: null
Dates: 2024-01-01
GUIDs: 00000000-0000-0000-0000-000000000000

Not yet supported

The following OData v4 features are not currently implemented:

Query options

$select — field projection
$expand — loading related entities
$count — total result count
$search — free-text search

Filter functions

String functions: tolower(), toupper(), trim(), length(), substring(), concat()
Date functions: year(), month(), day(), hour(), minute(), second()
Math functions: round(), floor(), ceiling()

Filter operators

not — logical negation
Lambda operators: any(), all()

Path traversal

Navigation properties: Orders/Customer/Name eq 'John'
Collection indexing

Contributions are welcome. Open an issue or PR on GitHub.

Error handling

If a schema name is not found in your config, a descriptive error is raised:

No schema configured for "Orders".

Add it to your config.exs:

    config :ex_odata4, schemas: %{
      "Orders" => MyApp.Orders
    }

License

MIT