Search Functionality

This module provides search capabilities and query parameter modeling for querying Dataverse installations.

SearchParameters

Model for specifying search query parameters.

class dartfx.dataverse.SearchParameters(*, q='*', type=None, subtree=None, sort=None, order=None, per_page=None, start=None, show_relevance=None, show_facets=None, fq=None, show_entity_ids=None, geo_point=None, geo_radius=None, metadata_fields=None)[source]

Bases: BaseModel

Represents the parameters that can be passed to the search endpoint. See https://guides.dataverse.org/en/latest/api/search.html

q: str

type: Literal['dataverse', 'dataset', 'file'] | list[Literal['dataverse', 'dataset', 'file']] | None

subtree: str | None

sort: Literal['name', 'date'] | None

order: Literal['asc', 'desc'] | None

per_page: int | None

start: int | None

show_relevance: bool | None

show_facets: bool | None

fq: list[str] | None

show_entity_ids: bool | None

geo_point: str | None

geo_radius: str | None

metadata_fields: list[str] | None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Query Examples

Basic Queries

from dartfx.dataverse import SearchParameters

# Match all datasets
params = SearchParameters()

# Text search
params = SearchParameters(q="climate change")

Field-Specific Search

params = SearchParameters(q="title:climate")
params = SearchParameters(q="authorName:Smith")
params = SearchParameters(q="description:temperature")

Boolean Operators

params = SearchParameters(q="climate AND temperature")
params = SearchParameters(q="climate OR weather")
params = SearchParameters(q="climate NOT politics")

Phrase Search

params = SearchParameters(q='"climate change"')
params = SearchParameters(q='"data analysis"')

Wildcards

params = SearchParameters(q="climat*")     # Prefix
params = SearchParameters(q="*climate*")   # Contains
params = SearchParameters(q="climat?")     # Single character

Range Queries & Filters

# Date range in filter
params = SearchParameters(
    q="*",
    fq=["publicationDate:[2020 TO 2026]"]
)

# Geographic proximity search
params = SearchParameters(
    q="*",
    geo_point="42.3601,-71.0589",
    geo_radius="50"
)

Response Format

Search results are returned as a dictionary with the following structure:

{
    "status": "OK",
    "data": {
        "total_count": 150,
        "start": 0,
        "items": [
            {
                "name": "Dataset Name",
                "type": "dataset",
                "url": "https://...",
                "identifier": "doi:...",
                "published_at": "2024-01-15",
                "description": "...",
            },
        ],
        "facets": [
            {
                "name": "subject_ss",
                "friendly_name": "Subject",
                "labels": [
                    {"label": "Medicine", "count": 45},
                    {"label": "Social Sciences", "count": 32},
                ]
            },
        ]
    }
}