# `BambooHR.Datasets`
[🔗](https://github.com/sgerrand/ex_bamboo_hr/blob/v0.6.0/lib/bamboo_hr/datasets.ex#L1)

Functions for querying the BambooHR Datasets API.

Datasets are the current, non-deprecated replacement for ad-hoc custom
reporting — see `BambooHR.Reports` for the older, still-supported saved
Custom Reports endpoints. Datasets endpoints live under different API
version segments than the rest of this client (`v1_2` for catalog/field
discovery, `v2` for querying data); every function here passes the
appropriate `api_version:` to `BambooHR.Client` for you.

# `get_dataset_data`

```elixir
@spec get_dataset_data(BambooHR.Client.t(), String.t(), [String.t()], keyword()) ::
  BambooHR.Client.response()
```

Queries a dataset and returns matching records.

Each row in the `"data"` array wraps its values under a `"fields"`
object. Use `get_dataset_fields/3` to discover available field names and
`get_field_options/4` to discover valid filter values.

## Parameters

  * `client` - Client configuration created with `BambooHR.Client.new/1`
  * `dataset_name` - Machine-readable dataset identifier (see `list_datasets/1`)
  * `fields` - List of field names to return
  * `opts` - Optional keyword list: `:filter` - an OData-style filter
    expression string (operators: `eq`, `ne`, `lt`, `le`, `gt`, `ge`,
    `and`, `or`, `in`); `:order_by` - comma-separated sort rules, each a
    field name followed by `asc` or `desc` (sorted fields must also
    appear in `fields`); `:page` - page number, defaults to 1;
    `:page_size` - records per page, defaults to 100, max 1000

## Examples

    iex> BambooHR.Datasets.get_dataset_data(client, "employee", ["firstName", "lastName", "status"],
    ...>   filter: "status eq 'Active'"
    ...> )
    {:ok, %{"data" => [%{"fields" => %{"firstName" => "Jane", "status" => "Active"}}], "meta" => %{"page" => 1}}}

# `get_dataset_fields`

```elixir
@spec get_dataset_fields(BambooHR.Client.t(), String.t(), map()) ::
  BambooHR.Client.response()
```

Retrieves a paginated list of field descriptors for a dataset.

Use the returned field `"name"` values in the `fields` argument to
`get_field_options/4` and `get_dataset_data/4`.

## Parameters

  * `client` - Client configuration created with `BambooHR.Client.new/1`
  * `dataset_name` - Machine-readable dataset identifier (see `list_datasets/1`)
  * `params` - Optional query params: `"page"` (default 1) and
    `"page_size"` (default 500, max 1000)

## Examples

    iex> BambooHR.Datasets.get_dataset_fields(client, "employee")
    {:ok, %{"name" => "employee", "fields" => [%{"name" => "status", "label" => "Status"}]}}

# `get_field_options`

```elixir
@spec get_field_options(BambooHR.Client.t(), String.t(), [String.t()], keyword()) ::
  BambooHR.Client.response()
```

Retrieves the allowed values for one or more fields in a dataset, for use
as filter values when querying data via `get_dataset_data/4`.

## Parameters

  * `client` - Client configuration created with `BambooHR.Client.new/1`
  * `dataset_name` - Machine-readable dataset identifier (see `list_datasets/1`)
  * `fields` - List of field names to get options for
  * `opts` - Optional keyword list: `:filters` - a map narrowing which
    options are returned (e.g. only options that exist for active
    employees); `:dependent_fields` - a map of field name to the other
    fields/values its options depend on

## Examples

    iex> BambooHR.Datasets.get_field_options(client, "employee", ["status"])
    {:ok, %{"status" => [%{"id" => "Active", "value" => "Active"}]}}

# `list_datasets`

```elixir
@spec list_datasets(BambooHR.Client.t()) :: BambooHR.Client.response()
```

Retrieves the catalog of datasets available for querying.

Each entry's `"name"` is the machine-readable identifier used as
`dataset_name` in `get_dataset_fields/3`, `get_field_options/4`, and
`get_dataset_data/4`.

## Parameters

  * `client` - Client configuration created with `BambooHR.Client.new/1`

## Examples

    iex> BambooHR.Datasets.list_datasets(client)
    {:ok, %{"datasets" => [%{"name" => "employee", "label" => "Employee"}]}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*