DSpace.API.Search (dspace_ex v0.1.0-alpha2)

Copy Markdown View Source

Operations for working with DSpace search ("discovery").

Provides functionality for searching across "DSpace objects" including items, collections, and communities. Supports faceted search, filtering, and sorting.

Summary

Types

filter()

A search filter specification.

search_options()

Options for search operations.

sort()

A sort specification.

Functions

fetch_config()

Fetches information on the search configuration.

fetch_facet_values(facet_name, options \\ [])

Fetches values for a specific search facet.

fetch_facets(options \\ [])

Fetches available facets for the given search context.

fetch_filters()

Fetches the available search filters and their specifications.

fetch_sort_options()

Fetches the available sort options.

query(options)

Performs a search query using the "Discovery" search endpoint.

Types

filter()

@type filter() :: %{filter: binary(), operator: binary(), value: binary()}

A search filter specification.

search_options()

@type search_options() :: [
  query: binary(),
  scope: binary(),
  configuration: atom() | binary(),
  filters: [filter()],
  sort: sort()
]

Options for search operations.

sort()

@type sort() :: binary() | atom() | {binary() | atom(), :asc | :desc}

A sort specification.

Functions

fetch_config()

@spec fetch_config() :: DSpace.API.Operation.JSON.t()

Fetches information on the search configuration.

Returns the available filters, operators, and sort options.

fetch_facet_values(facet_name, options \\ [])

@spec fetch_facet_values(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Fetches values for a specific search facet.

Retrieves the possible values and their counts for a single facet field. Useful for building facet selection interfaces.

This operation can be streamed.

Parameters

  • facet_name - The name of the facet (e.g., "author", "subject", "dateIssued")
  • options - Search context and pagination options, see query/1 options

fetch_facets(options \\ [])

@spec fetch_facets(keyword()) :: DSpace.API.Operation.JSON.t()

Fetches available facets for the given search context.

Returns facets that can be used to refine search results. Uses the same search context (query, scope, configuration, filters) but returns facet information instead of search results.

This operation can be streamed.

Parameters

  • options - Search context and pagination options, see query/1 options

fetch_filters()

@spec fetch_filters() :: DSpace.API.Operation.JSON.t()

Fetches the available search filters and their specifications.

fetch_sort_options()

@spec fetch_sort_options() :: DSpace.API.Operation.JSON.t()

Fetches the available sort options.

query(options)

@spec query(query_string :: binary() | search_options()) ::
  DSpace.API.Operation.JSON.t()

Performs a search query using the "Discovery" search endpoint.

This function takes either

  • a search query as a string or
  • a search context as a keyword list of options

This operation can be streamed.

Options

  • :query - The search query string (optional for scope-only searches)
  • :scope - UUID of a specific DSpace container (community, collection, etc.) to limit search scope
  • :configuration - Name of Discovery configuration to use as a string or atom
    • :workspace - Search user's draft items (requires authentication)
    • :workflow - Search editorial workflow items (requires authentication)
    • Custom configuration names as defined in the DSpace instance's discovery.xml
  • :filters - List of filter maps to refine search results. Each filter must have:
    • :filter - The filter (e.g., "itemtype", "title", "author", "subject", "dateIssued")
    • :operator - The filter operator (e.g., "equals", "notequals", "contains", "notcontains", "authority", "notauthority")
    • :value - The filter value to match against
  • :sort - Sort specification for results. Can be:
    • A string or atom for field name (defaults to ascending order)
    • A tuple {field, direction} where direction is :asc or :desc. Common sort fields:
      • "score" - Relevance score (use :desc for most relevant first)
      • "dc.date.issued" - Publication date
      • "dc.date.accessioned" - Date added to repository
      • "dc.title" - Title (use :asc for A-Z alphabetical)
  • :page - Page number (0-based, defaults to 0)
  • :size - Number of items per page (usually defaults to 20)