ftmq.api

@cache
def get_catalog() -> Catalog:
    """The catalog of queryable datasets, reconciled with the store.

    `settings.catalog` *describes* datasets, but the store *decides* which
    exist. A name present in the store and missing from the catalog is added
    as a bare dataset, so a catalog naming something else - or no catalog at
    all - can never leave the store's own datasets un-queryable (the dataset
    filter validates against this catalog).
    """
    catalog = Catalog()
    if settings.catalog is not None:
        catalog = Catalog._from_uri(settings.catalog)
    undeclared = get_store_datasets() - catalog.names
    if undeclared:
        if catalog.names:
            log.warning(
                f"Datasets in store but not in catalog: `{', '.join(sorted(undeclared))}`",
                catalog=settings.catalog,
            )
        catalog.datasets = catalog.datasets + [
            Dataset(name=name, title=name) for name in sorted(undeclared)
        ]
    return catalog

def get_entity(entity_id: str, params: "RetrieveParams") -> Entity:
    """The entity by id, or by a referent id the store's linker resolves."""
    # the statements of a resolved store carry the canonical id
    view = get_view()
    proxy = view.get_entity(get_store().linker.get_canonical(entity_id))
    proxy = proxy or view.get_entity(entity_id)
    if proxy is None:
        raise HTTPException(404, detail=[f"Entity `{entity_id}` not found."])
    return shape(proxy, params)

def get_store_datasets() -> set[str]:
    """The dataset names the configured store actually holds."""
    try:
        return set(get_store().scope.leaf_names)
    except Exception as e:
        # never make the catalog (and with it the app's import) depend on the
        # store being reachable - an unconfigured catalog degrades to empty
        log.error(f"Cannot read datasets from store: `{e}`", store=settings.store_uri)
        return set()

def shape(proxy: Entity, params: "RetrieveParams") -> Entity:
    """Dehydrate an entity, or reduce it to its featured properties, as asked."""
    if params.dehydrate:
        return get_dehydrated_entity(proxy)
    if params.featured:
        return get_featured_entity(proxy)
    return proxy

def build_query(request: Request, authenticated: bool | None = False) -> Query:
    """Build a [`Query`][ftmq.Query] from a request's query params.

    The flat filter grammar is the Aleph one (`filter:` / `exclude:` /
    `empty:`, `sort`, `limit` / `offset`, `metric:<func>` / `facet`) parsed via
    [`Query.from_params`][ftmq.Query.from_params]. An optional `rql=` param
    carries a full nested [RQL][ftmq.Query.from_rql] filter tree (and, if
    present, its aggregations and its `select` projection); it overrides the
    flat filter grammar while `sort` / `limit` / `offset` keep coming from the
    plain params.

    Non-query params (`q`, `api_key`, retrieve flags) are ignored by the
    parser. The limit is capped to `settings.default_limit` and each facet
    size to `settings.max_facet_size`, unless the request is authenticated;
    datasets are validated against the catalog.

    Raises:
        HTTPException: 422 for a dataset not in the catalog.
        QueryError: For invalid filter fields, values or RQL (handled as 400
            upstream).
    """
    params = params_from_request(request)
    q = Query.from_params(params)
    rql = params.get("rql")
    if rql:
        rql_q = Query.from_rql(rql[0])
        q = q._chain(
            q=rql_q.q,
            aggregations=rql_q.aggregations or q.aggregations,
            selection=rql_q.selection or q.selection,
        )
    limit = q.limit if q.limit is not None else settings.default_limit
    if not authenticated:
        limit = min(limit, settings.default_limit)
        sizes = {r: q.get_facet_size(r) for r in q.facet_sizes}
        q = q._chain(
            facet_sizes={r: min(n, settings.max_facet_size) for r, n in sizes.items()}
        )
    offset = q.offset or 0
    q = q[offset : offset + limit]
    names = get_catalog().names
    invalid = q.dataset_names - names
    if invalid:
        raise HTTPException(
            422,
            detail=[
                f"Invalid dataset: `{', '.join(sorted(invalid))}` - "
                f"available: `{', '.join(sorted(names)) or 'none'}`"
            ],
        )
    return q

def params_from_request(request: Request) -> dict[str, list[str]]:
    """Collect the request query params as a dict of lists (starlette's
    `QueryParams.items()` drops repeated keys)."""
    params: dict[str, list[str]] = defaultdict(list)
    for key, value in request.query_params.multi_items():
        params[key].append(value)
    return dict(params)

def build_facets(aggregations: AggregatorResult, query: Query) -> dict[str, Any]:
    """Grouped aggregations as Aleph `facets` with buckets of
    `{value, label, count, metrics: {field: {func: value}}}`, ranked by the
    query's `facet_sort` metric, else by entity count.

    Args:
        aggregations: The computed aggregations, with bucket counts.
        query: The request query.

    Returns:
        The Aleph-style `facets`.
    """
    facets: dict[str, Any] = {}
    order = query.facet_sort
    for field, results in aggregations.get("groups", {}).items():
        counts = results.get("count", {}).get("id", {})
        buckets = {gval: _bucket(gval, count) for gval, count in counts.items()}
        for agg in query.aggregations:
            if field not in {g.wire for g in agg.groups}:
                continue
            for gval, value in results.get(agg.func, {}).get(agg.key, {}).items():
                bucket = buckets.setdefault(gval, _bucket(gval, 0))
                bucket["metrics"].setdefault(agg.key, {})[agg.func] = value
        values = sorted(buckets.values(), key=lambda v: (-v["count"], v["value"]))
        if order is not None:
            keyed = [
                (v["metrics"].get(order.ref.wire, {}).get(order.func), v)
                for v in values
            ]
            # stable: ties keep the count order
            present = [(m, v) for m, v in keyed if m is not None]
            present.sort(key=lambda x: x[0], reverse=not order.ascending)
            values = [v for _, v in present] + [v for m, v in keyed if m is None]
        total = aggregations.get("count", {}).get(field, len(values))
        facets[field] = {"values": values, "total": total}
    return facets

def build_filters(query: Query) -> dict[str, list[str]]:
    """The applied positive filters as `{field: [values]}` (empty for nested queries)."""
    try:
        params = query.to_params()
    except QueryError:
        return {}
    return {
        key[len("filter:") :]: list(values)
        for key, values in params.items()
        if key.startswith("filter:")
    }

def build_metrics(aggregations: AggregatorResult, query: Query) -> dict[str, Any]:
    """The query's ungrouped aggregations as `{field: {func: value}}`.

    Args:
        aggregations: The computed aggregations.
        query: The request query; only its aggregations are reported.

    Returns:
        The Aleph-style `metrics`.
    """
    metrics: dict[str, Any] = defaultdict(dict)
    for agg in query.aggregations:
        value = aggregations.get(agg.func, {}).get(agg.key)
        if value is not None:
            metrics[agg.key][agg.func] = value
    return dict(metrics)

def with_bucket_counts(query: Query) -> Query:
    """Add an entity count per facet, so every bucket has its `count`, and the
    facet's distinct values, its `total`.

    Args:
        query: The request query.

    Returns:
        The query to compute the aggregations with.
    """
    groups = groupers(query.aggregations)
    if not groups:
        return query
    totals = {make_agg("count", g) for g in groups}
    return query._chain(
        aggregations={*query.aggregations, *totals, make_agg("count", IdRef(), groups)}
    )

def get_nested(view: View, entities: list[Entity], params: RetrieveParams) -> list:
    """The entities the given ones reference, to inline with `nested=true`."""
    if not params.nested:
        return []
    adjacents = view.get_adjacents(entities)
    if params.dehydrate_nested:
        return [get_dehydrated_entity(e) for e in adjacents]
    return list(adjacents)