defmodule PS2.API.QueryBuilder do
@moduledoc """
A module for creating Census API queries in a clean manner via pipelines.
### Example
iex> import PS2.API.QueryBuilder
PS2.API.QueryBuilder
iex> alias PS2.API.Query
PS2.API.Query
iex> query = Query.new(collection: "character")
...> |> term("character_id", "5428011263335537297")
...> |> show(["character_id", "name.en", "faction_id"])
...> |> limit(3)
...> |> exact_match_first(true)
%PS2.API.Query{
collection: "character",
joins: [],
sort: nil,
params: %{
"c:exactMatchFirst" => true,
"c:limit" => 3,
"c:show" => "character_id,name.en,faction_id",
"character_id" => {"", "5428011263335537297"}
},
tree: nil
}
iex> PS2.API.encode query
{:ok, "character?c:exactMatchFirst=true&c:limit=3&c:show=character_id,name.en,faction_id&character_id=5428011263335537297"}
You can then send the query to the api using `PS2.API.query/1`.
## Search Modifiers
The Census API provides [search modifiers](https://census.daybreakgames.com/#search-modifier) for filtering query results.
You can pass an atom as the third parameter in `term/4` representing one of
these search modifiers. The recognized atoms are the following:
```
:greater_than
:greater_than_or_equal
:less_than
:less_than_or_equal
:starts_with
:contains
:not
```
For example: `term(query_or_join, "name.first_lower", "wrel", :starts_with)`
## Joining Queries
You can use `Join`s to gather data from multiple collections within one query,
like so:
```elixir
import PS2.API.QueryBuilder
alias PS2.API.{Query, Join}
online_status_join =
# Note we could use Join.new(collection: "characters_online_status", show: "online_status" ...)
%Join{}
|> collection("characters_online_status")
|> show("online_status")
|> inject_at("online_status")
|> list(true)
query =
%Query{}
|> collection("character")
|> join(online_status_join)
```
When the query `q` is sent to the API, the result with have an extra field,
"online_status", which contains the result of the `Join` (the player's
online status.)
You can create as many adjacent `Join`s as you'd like by repeatedly piping
a query through `QueryBuilder.join/2`. You can also nest `Join`s via
`QueryBuilder.join/2` when you pass a Join as the first argument instead
of a Query.
```elixir
import PS2.API.QueryBuilder
alias PS2.API.{Query, Join}
char_achieve_join =
Join.new(collection: "characters_achievement", on: "character_id")
char_name_join =
Join.new(collection: "character_name", on: "character_id", inject_at: "c_name")
online_status_join =
Join.new(collection: "characters_online_status")
|> join(char_name_join)
|> join(char_achieve_join)
query =
%Query{}
|> collection("character")
|> term("name.first", "Snowful")
|> show(["character_id", "faction_id"])
|> join(online_status_join)
```
## Trees
You can organize the returned data by a field within the data, using the
`QueryBuilder.tree/2`.
```elixir
import PS2.API.QueryBuilder
alias PS2.API.{Query, Tree}
%Query{}
|> collection("world_event")
|> term("type", "METAGAME")
|> lang("en")
|> tree(
%Tree{}
|> field("world_id")
|> list(true)
)
```
"""
@modifier_map %{
greater_than: ">",
greater_than_or_equal: "]",
less_than: "<",
less_than_or_equal: "[",
starts_with: "^",
contains: "*",
not: "!"
}
@type modifer ::
:greater_than
| :greater_than_or_equal
| :less_than
| :less_than_or_equal
| :starts_with
| :contains
| :not
| nil
@type collection_name :: String.t()
@type field_name :: String.t()
alias PS2.API.{Query, Join, Tree}
@doc """
Set the collection of the query/join.
"""
@spec collection(Query.t(), collection_name) :: Query.t()
@spec collection(Join.t(), collection_name) :: Join.t()
def collection(query_or_join, collection_name)
def collection(%Query{} = query, collection_name),
do: %Query{query | collection: collection_name}
def collection(%Join{} = join, collection), do: %Join{join | collection: collection}
@doc """
Adds a c:show term. Overwrites previous params of the same name.
### API Documentation:
Only include the provided fields from the object within the result.
"""
@spec show(Query.t(), String.t() | list(String.t())) :: Query.t()
@spec show(Join.t(), String.t() | list(String.t())) :: Join.t()
def show(query_or_join, value)
def show(%Query{} = query, values) when is_list(values), do: show(query, Enum.join(values, ","))
def show(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:show", value)}
def show(%Join{} = join, values) when is_list(values), do: show(join, Enum.join(values, "'"))
def show(%Join{} = join, value), do: %Join{join | params: Map.put(join.params, "show", value)}
@doc """
Adds a c:hide term. Overwrites previous params of the same name.
### API Documentation:
Include all field except the provided fields from the object within the result.
"""
@spec hide(Query.t(), String.t() | list(String.t())) :: Query.t()
@spec hide(Join.t(), String.t() | list(String.t())) :: Join.t()
def hide(query_or_join, values)
def hide(%Query{} = query, values) when is_list(values), do: hide(query, Enum.join(values, ","))
def hide(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:hide", value)}
def hide(%Join{} = join, values) when is_list(values), do: hide(join, Enum.join(values, "'"))
def hide(%Join{} = join, field), do: %Join{join | params: Map.put(join.params, "hide", field)}
@doc """
Add a term to filter query results. i.e. filter a query by character ID: `.../character?character_id=1234123412341234123`
"""
@spec term(Query.t(), String.t() | atom, any, modifer) :: Query.t()
@spec term(Join.t(), String.t() | atom, any, modifer) :: Join.t()
def term(query_or_join, field, value, modifier \\ nil)
def term(%Query{} = query, field, value, modifier),
do: %Query{
query
| params: Map.put(query.params, field, {Map.get(@modifier_map, modifier, ""), value})
}
def term(%Join{} = join, field, value, modifier) do
term_value = {Map.get(@modifier_map, modifier, ""), value}
%Join{
join
| params:
Map.update(join.params, :terms, %{field => term_value}, &Map.put(&1, field, term_value))
}
end
@doc """
Adds a join to a query.
See the "Using c:join to join collections dynamically"
section at https://census.daybreakgames.com/#query-commands to learn more about joining
queries.
### c:join API Documentation:
Meant to replace c:resolve, useful for dynamically joining (resolving)
multiple data types in one query.
"""
@spec join(Query.t(), Join.t()) :: Query.t()
@spec join(Join.t(), Join.t()) :: Join.t()
def join(query_or_join, join)
def join(%Query{} = query, %Join{} = join), do: %Query{query | joins: [join | query.joins]}
def join(%Join{} = join, %Join{} = new_join), do: %Join{join | joins: [new_join | join.joins]}
@doc """
Adds a sort term (to a Join or Tree).
Specifies whether the result should be a list (true) or a single record (false). Defaults to false.
"""
@spec list(Join.t(), boolean()) :: %Join{}
@spec list(Tree.t(), boolean()) :: %Tree{}
def list(tree_or_join, boolean)
def list(%Join{} = join, boolean),
do: %Join{join | params: Map.put(join.params, "list", PS2.Utils.boolean_to_integer(boolean))}
def list(%Tree{} = tree, boolean),
do: %Tree{tree | terms: Map.put(tree.terms, :list, PS2.Utils.boolean_to_integer(boolean))}
# ~~Query specific functions~~
@doc """
Adds a c:sort term. Overwrites previous params of the same name.
### API Documentation:
Sort the results by the field(s) provided.
"""
@spec sort(Query.t(), Query.sort_terms()) :: Query.t()
def sort(%Query{} = query, %{} = sort_terms), do: %Query{query | sort: sort_terms}
@doc """
Adds a c:has term. Overwrites previous params of the same name.
### API Documentation:
Include objects where the specified field exists, regardless
of the value within that field.
"""
@spec has(Query.t(), String.t() | list()) :: Query.t()
def has(%Query{} = query, values) when is_list(values), do: has(query, Enum.join(values, ","))
def has(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:has", value)}
@doc """
Adds a c:resolve term. Overwrites previous params of the same name.
**Note** that `join/3` is recommended over `resolve/2`, as resolve relies
on supported collections to work.
### API Documentation:
"Resolve" information by merging data from another collection and include
the detailed object information for the provided fields from the object
within the result (multiple field names separated by a comma).\n
*Please note that the resolve will only function if the initial query contains
the field to be resolved on. For instance, resolving leader on outfit requires
that leader_character_id be in the initial query.
"""
@spec resolve(Query.t(), String.t() | [String.t()]) :: Query.t()
def resolve(%Query{} = query, collection),
do: %Query{query | params: Map.put(query.params, "c:resolve", collection)}
@doc """
Adds a c:case (sensitivity) term. Overwrites previous params of the same name.
### API Documentation:
Set whether a search should be case-sensitive, `true` means
case-sensitive. true is the default. Note that using this command may slow
down your queries. If a lower case version of a field is available use that
instead for faster performance.
"""
@spec case_sensitive(Query.t(), boolean()) :: Query.t()
def case_sensitive(%Query{} = query, boolean),
do: %Query{query | params: Map.put(query.params, "c:case", boolean)}
@doc """
Adds a c:limit term. Overwrites previous params of the same name.
### API Documentation:
Limit the results to at most N [`value`] objects.
"""
@spec limit(Query.t(), integer()) :: Query.t()
def limit(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:limit", value)}
@doc """
Adds a c:limitPerDB term. Overwrites previous params of the same name.
### API Documentation:
Limit the results to at most (N * number of databases) objects.\n
*The data type ps2/character is distributed randomly across 20
databases. Using c:limitPerDb will have more predictable results on
ps2/character than c:limit will.
"""
@spec limit_per_db(Query.t(), integer()) :: Query.t()
def limit_per_db(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:limitPerDB", value)}
@doc """
Adds a c:start term. Overwrites previous params of the same name.
### API Documentation:
Start with the Nth object within the results of the query.\n
*Please note that c:start will have unusual behavior when
querying ps2/character which is distributed randomly across
20 databases.
"""
@spec start(Query.t(), integer()) :: Query.t()
def start(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:start", value)}
@doc """
Adds a c:includeNull term. Overwrites previous params of the same name.
### API Documentation:
Include `NULL` values in the result. By default this is false. For
example, if the `name.fr` field of a vehicle is `NULL` the field `name.fr`
will not be included in the response by default. Add the
c:includeNull=true command if you want the value name.fr : `NULL` to be
returned in the result.
"""
@spec include_null(Query.t(), boolean()) :: Query.t()
def include_null(%Query{} = query, boolean),
do: %Query{query | params: Map.put(query.params, "c:includeNull", boolean)}
@doc """
Adds a c:lang term. Overwrites previous params of the same name.
### API Documentation:
For internationalized strings, remove all translations except the one specified.
"""
@spec lang(Query.t(), String.t()) :: Query.t()
def lang(%Query{} = query, value),
do: %Query{query | params: Map.put(query.params, "c:lang", value)}
@doc """
Adds a c:tree term
### API Documentaion:
Useful for rearranging lists of data into trees of data. See below for details.
"""
@spec tree(Query.t(), Tree.t()) :: Query.t()
def tree(%Query{} = query, %Tree{} = tree), do: %Query{query | tree: tree}
@doc """
Adds a c:timing term. Overwrites previous params of the same name.
### API Documentation:
Shows the time taken by the involved server-side queries and resolves.
"""
@spec timing(Query.t(), boolean()) :: Query.t()
def timing(%Query{} = query, boolean),
do: %Query{query | params: Map.put(query.params, "c:timing", boolean)}
@doc """
Adds a c:exactMatchFirst term. Overwrites previous params of the same name.
### API Documentation:
When using a regex search (=^ or =*) c:exactMatchFirst=true will cause
exact matches of the regex value to appear at the top of the result list
despite the value of c:sort.
"""
@spec exact_match_first(Query.t(), boolean()) :: Query.t()
def exact_match_first(%Query{} = query, boolean),
do: %Query{query | params: Map.put(query.params, "c:exactMatchFirst", boolean)}
@doc """
Adds a c:distinct term. Overwrites previous params of the same name.
### API Documentation:
Get the distinct values of the given field. For example to get the
distinct values of ps2.item.max_stack_size use
`http://census.daybreakgames.com/get/ps2/item?c:distinct=max_stack_size`.
Results are capped at 20,000 values.
"""
@spec distinct(Query.t(), boolean()) :: Query.t()
def distinct(%Query{} = query, boolean),
do: %Query{query | params: Map.put(query.params, "c:distinct", boolean)}
@doc """
Adds a c:retry term. Overwrites previous params of the same name.
### API Documentation:
If `true`, query will be retried one time. Default value is true.
If you prefer your query to fail quickly pass c:retry=false.
"""
@spec retry(Query.t(), boolean()) :: Query.t()
def retry(%Query{} = query, boolean),
do: %Query{query | params: Map.put(query.params, "c:retry", boolean)}
# ~~Join specific functions~~
@doc """
Adds an `on:` term. `field` is the field on the parent/leading collection to compare with the join's field
(optionally specified with the `to/2` function).
### API Documentation:
The field on this type to join on, i.e. item_id. Will default to {this_type}_id or {other_type}_id if not provided.
"""
@spec on(Join.t(), field_name) :: %Join{}
def on(%Join{} = join, field), do: %Join{join | params: Map.put(join.params, "on", field)}
@doc """
Adds a `to:` term. `field` is the field on the joined collection to compare with the parent/leading field
(optionally specified with the `on/2` function).
### API Documentation:
The field on the joined type to join to, i.e. attachment_item_id. Will default to on if on is provide, otherwise
will default to {this_type}_id or {other_type}_id if not provided.
"""
@spec to(Join.t(), field_name) :: %Join{}
def to(%Join{} = join, field), do: %Join{join | params: Map.put(join.params, "to", field)}
@doc """
Adds an `injected_at:` term. `field` is the name of the new field where the result of the join is inserted.
### API Documentation:
The field name where the joined data should be injected into the returned document.
"""
@spec inject_at(Join.t(), field_name) :: %Join{}
def inject_at(%Join{} = join, field),
do: %Join{join | params: Map.put(join.params, "inject_at", field)}
@doc """
Adds an `outer:` term. Note: where the API docs specify `1`, `true` should be passed, and `false` in place of `0`.
### API Documentation:
1 if you wish to do an outer join (include non-matches), 0 if you wish to do an inner join (exclude non-matches).
Defaults to 1- do an outer join, include non-matches.
"""
@spec outer(Join.t(), boolean()) :: %Join{}
def outer(%Join{} = join, boolean),
do: %Join{join | params: Map.put(join.params, "outer", PS2.Utils.boolean_to_integer(boolean))}
# ~~Tree specific functions~~
@doc """
Adds a `start:` term.
### API Documentaion:
Used to tell the tree where to start. By default, the list of objects at the root will be formatted as a tree.
"""
@spec start_field(Tree.t(), field_name) :: %Tree{}
def start_field(%Tree{} = tree, field),
do: %Tree{tree | terms: Map.put(tree.terms, :start, field)}
@doc """
Adds a `field:` term.
### API Documentation:
The field to remove and use as in the data structure, or tree.
"""
@spec field(Tree.t(), field_name) :: %Tree{}
def field(%Tree{} = tree, field), do: %Tree{tree | terms: Map.put(tree.terms, :field, field)}
@doc """
Add a `prefix:` term.
### API Documentation:
A prefix to add to the field value to make it more readable. For example, if the field is "faction_id" and prefix
is "f_", path will be f_1, f_2, f_3 etc.
"""
@spec prefix(Tree.t(), String.t()) :: %Tree{}
def prefix(%Tree{} = tree, prefix),
do: %Tree{tree | terms: Map.put(tree.terms, :prefix, prefix)}
end
