GraphApi.Delta (GraphApi v1.0.0-rc.1)

Delta query support for tracking incremental changes.

Delta queries return changes since the last sync point. The first call returns the full dataset plus a deltaLink. Subsequent calls with the deltaLink return only items that changed (created, updated, or deleted).

How it works

Initial sync: Delta.query("/users/delta", client: client) Returns all current items + a delta_link for future syncs.
Incremental sync: Delta.query(delta_link, client: client) Returns only changes since the last sync. Deleted items have an @removed property.

Examples

# Initial sync
{:ok, page} = Delta.query("/users/delta", client: client)
# page.items => [all current users]
# page.delta_link => "https://graph...?$deltatoken=..."

# Store delta_link, then later:
{:ok, changes} = Delta.query(page.delta_link, client: client)
# changes.items => only what changed

# Collect all pages at once
{:ok, result} = Delta.collect_all("/users/delta", client: client)

Supported resources

/users/delta
/groups/delta
/groups/{id}/members/delta
/me/messages/delta or /users/{id}/messages/delta
/me/mailFolders/{id}/messages/delta
/me/events/delta or /users/{id}/events/delta
/drives/{id}/root/delta

Summary

Types

delta_page()

Functions

collect_all(path_or_link, opts \\ [])

Collects all pages of a delta query into a single result.

query(path_or_link, opts \\ [])

Performs a delta query and returns a single page of results.

stream(first_page, opts \\ [])

Creates a lazy Stream that yields items from all pages of a delta query.

Types

delta_page()

@type delta_page() :: %{
  items: [map()],
  delta_link: String.t() | nil,
  next_link: String.t() | nil
}

Functions

collect_all(path_or_link, opts \\ [])

@spec collect_all(
  String.t(),
  keyword()
) :: {:ok, delta_page()} | {:error, term()}

Collects all pages of a delta query into a single result.

Follows @odata.nextLink pages until a deltaLink is received. Returns all accumulated items plus the final delta_link.

Examples

{:ok, result} = Delta.collect_all("/users/delta", client: client)
# result.items => all items across all pages
# result.delta_link => "https://...?$deltatoken=..."

query(path_or_link, opts \\ [])

@spec query(
  String.t(),
  keyword()
) :: {:ok, delta_page()} | {:error, term()}

Performs a delta query and returns a single page of results.

Accepts either a relative path (e.g., "/users/delta") for initial sync, or a full deltaLink/nextLink URL for subsequent pages.

Options

Same as other resource functions: :client, :query, :access_token, :api_version, :as

Examples

# Initial sync
{:ok, page} = Delta.query("/users/delta", client: client)

# Follow deltaLink for changes
{:ok, changes} = Delta.query(page.delta_link, client: client)

# With OData query
query = OData.new() |> OData.select(["id", "displayName"]) |> OData.top(100)
{:ok, page} = Delta.query("/users/delta", client: client, query: query)

stream(first_page, opts \\ [])

@spec stream(
  delta_page(),
  keyword()
) :: Enumerable.t()

Creates a lazy Stream that yields items from all pages of a delta query.

The stream follows @odata.nextLink pages automatically. After the stream is consumed, use collect_all/2 if you need the delta_link.

Examples

{:ok, first_page} = Delta.query("/users/delta", client: client)

first_page
|> Delta.stream(client: client)
|> Stream.filter(fn item -> item["@removed"] == nil end)
|> Enum.to_list()