View Source PS2.API.QueryBuilder (PlanetSide 2 API v0.3.5)
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 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
:notFor example: term(query_or_join, "name.first_lower", "wrel", :starts_with)
Joining Queries
You can use Joins to gather data from multiple collections within one query,
like so:
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 Joins as you'd like by repeatedly piping
a query through QueryBuilder.join/2. You can also nest Joins via
QueryBuilder.join/2 when you pass a Join as the first argument instead
of a Query.
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.
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)
)Link to this section Summary
Functions
Adds a c:case (sensitivity) term. Overwrites previous params of the same name.
Set the collection of the query/join.
Adds a c:distinct term. Overwrites previous params of the same name.
Adds a c:exactMatchFirst term. Overwrites previous params of the same name.
Adds a field: term.
Adds a c:has term. Overwrites previous params of the same name.
Adds a c:hide term. Overwrites previous params of the same name.
Adds a c:includeNull term. Overwrites previous params of the same name.
Adds an injected_at: term. field is the name of the new field where the result of the join is inserted.
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.
Adds a c:lang term. Overwrites previous params of the same name.
Adds a c:limit term. Overwrites previous params of the same name.
Adds a c:limitPerDB term. Overwrites previous params of the same name.
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.
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).
Adds an outer: term. Note: where the API docs specify 1, true should be passed, and false in place of 0.
Add a prefix: term.
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.
Adds a c:retry term. Overwrites previous params of the same name.
Adds a c:show term. Overwrites previous params of the same name.
Adds a c:sort term. Overwrites previous params of the same name.
Adds a c:start term. Overwrites previous params of the same name.
Adds a start: term.
Add a term to filter query results. i.e. filter a query by character ID: .../character?character_id=1234123412341234123
Adds a c:timing term. Overwrites previous params of the same name.
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).
Adds a c:tree term
Link to this section Types
Link to this section Functions
Specs
case_sensitive(PS2.API.Query.t(), boolean()) :: PS2.API.Query.t()
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.
Specs
collection(PS2.API.Query.t(), collection_name()) :: PS2.API.Query.t()
collection(PS2.API.Join.t(), collection_name()) :: PS2.API.Join.t()
Set the collection of the query/join.
Specs
distinct(PS2.API.Query.t(), boolean()) :: PS2.API.Query.t()
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.
Specs
exact_match_first(PS2.API.Query.t(), boolean()) :: PS2.API.Query.t()
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.
Specs
field(PS2.API.Tree.t(), field_name()) :: %PS2.API.Tree{terms: term()}
Adds a field: term.
API Documentation:
The field to remove and use as in the data structure, or tree.
Specs
has(PS2.API.Query.t(), String.t() | list()) :: PS2.API.Query.t()
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.
Specs
hide(PS2.API.Query.t(), String.t() | [String.t()]) :: PS2.API.Query.t()
hide(PS2.API.Join.t(), String.t() | [String.t()]) :: PS2.API.Join.t()
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.
Specs
include_null(PS2.API.Query.t(), boolean()) :: PS2.API.Query.t()
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.
Specs
inject_at(PS2.API.Join.t(), field_name()) :: %PS2.API.Join{ collection: term(), joins: term(), params: term() }
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.
Specs
join(PS2.API.Query.t(), PS2.API.Join.t()) :: PS2.API.Query.t()
join(PS2.API.Join.t(), PS2.API.Join.t()) :: PS2.API.Join.t()
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.
Specs
lang(PS2.API.Query.t(), String.t()) :: PS2.API.Query.t()
Adds a c:lang term. Overwrites previous params of the same name.
API Documentation:
For internationalized strings, remove all translations except the one specified.
Specs
limit(PS2.API.Query.t(), integer()) :: PS2.API.Query.t()
Adds a c:limit term. Overwrites previous params of the same name.
API Documentation:
Limit the results to at most N [value] objects.
Specs
limit_per_db(PS2.API.Query.t(), integer()) :: PS2.API.Query.t()
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.
*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.
Specs
list(PS2.API.Join.t(), boolean()) :: %PS2.API.Join{ collection: term(), joins: term(), params: term() }
list(PS2.API.Tree.t(), boolean()) :: %PS2.API.Tree{terms: term()}
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.
Specs
on(PS2.API.Join.t(), field_name()) :: %PS2.API.Join{ collection: term(), joins: term(), params: term() }
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.
Specs
outer(PS2.API.Join.t(), boolean()) :: %PS2.API.Join{ collection: term(), joins: term(), params: term() }
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.
Specs
prefix(PS2.API.Tree.t(), String.t()) :: %PS2.API.Tree{terms: term()}
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 "factionid" and prefix is "f", path will be f_1, f_2, f_3 etc.
Specs
resolve(PS2.API.Query.t(), String.t() | [String.t()]) :: PS2.API.Query.t()
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).
*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.
Specs
retry(PS2.API.Query.t(), boolean()) :: PS2.API.Query.t()
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.
Specs
show(PS2.API.Query.t(), String.t() | [String.t()]) :: PS2.API.Query.t()
show(PS2.API.Join.t(), String.t() | [String.t()]) :: PS2.API.Join.t()
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.
Specs
sort(PS2.API.Query.t(), PS2.API.Query.sort_terms()) :: PS2.API.Query.t()
Adds a c:sort term. Overwrites previous params of the same name.
API Documentation:
Sort the results by the field(s) provided.
Specs
start(PS2.API.Query.t(), integer()) :: PS2.API.Query.t()
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.
*Please note that c:start will have unusual behavior when querying ps2/character which is distributed randomly across 20 databases.
Specs
start_field(PS2.API.Tree.t(), field_name()) :: %PS2.API.Tree{terms: term()}
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.
Specs
term(PS2.API.Query.t(), String.t() | atom(), any(), modifer()) :: PS2.API.Query.t()
term(PS2.API.Join.t(), String.t() | atom(), any(), modifer()) :: PS2.API.Join.t()
Add a term to filter query results. i.e. filter a query by character ID: .../character?character_id=1234123412341234123
Specs
timing(PS2.API.Query.t(), boolean()) :: PS2.API.Query.t()
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.
Specs
to(PS2.API.Join.t(), field_name()) :: %PS2.API.Join{ collection: term(), joins: term(), params: term() }
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.
Specs
tree(PS2.API.Query.t(), PS2.API.Tree.t()) :: PS2.API.Query.t()
Adds a c:tree term
API Documentaion:
Useful for rearranging lists of data into trees of data. See below for details.