Method select

app/api/agentops/api/db/clickhouse/models.py:308–375

Query the database and return a list of model instances. This method builds and executes a SQL query based on the provided parameters and class configuration, then converts the query results into model instances. Args: fields: Optional list of fields to select.

(
        cls: Type[TClickhouseModel],
        *,
        fields: Optional[SelectFields] = None,
        filters: Optional[FilterFields] = None,
        search: Optional[str] = None,
        order_by: Optional[str] = None,
        offset: Optional[int] = None,
        limit: Optional[int] = None,
    )

    @classmethod
    async def select(
        cls: Type[TClickhouseModel],
        *,
        fields: Optional[SelectFields] = None,
        filters: Optional[FilterFields] = None,
        search: Optional[str] = None,
        order_by: Optional[str] = None,
        offset: Optional[int] = None,
        limit: Optional[int] = None,
    ) -> list[TClickhouseModel]:
        """Query the database and return a list of model instances.

        This method builds and executes a SQL query based on the provided parameters and
        class configuration, then converts the query results into model instances.

        Args:
            fields: Optional list of fields to select. Defaults to cls.selectable_fields.
                Example: ["id", "name", "email"]
            filters: Optional dictionary of filters to apply. Keys must be defined in
                cls.filterable_fields to be effective.
                Example: {"project_id": "123", "start_time": "2023-01-01"}
            search: Optional search string to apply to all searchable fields configured in
                cls.searchable_fields. For LIKE/ILIKE searches, wildcards (%)
                are automatically added if not present.
                Example: "authentication" will search all configured fields for "authentication"
            order_by: Optional ORDER BY clause (without the "ORDER BY" prefix).
                Example: "created_at DESC"
            offset: Optional OFFSET value for pagination.
            limit: Optional LIMIT value to restrict the number of results.

        Returns:
            List[TClickhouseModel]: A list of model instances of the exact calling class type,
            with each instance created from a row in the query results. The return type is
            properly typed using generics to preserve the concrete subclass type.

        Example:
            ```python
            # Get last 10 traces for a specific project
            traces = await TraceModel.select(
                filters={"project_id": "abc123"},
                order_by="timestamp DESC",
                limit=10
            )

            # Search for traces with spans containing "authentication"
            traces = await TraceModel.select(
                filters={"project_id": "abc123"},
                search="authentication",
                limit=10
            )

            # Access model properties on the results
            for trace in traces:
                print(f"Trace {trace.trace_id}: {trace.total_tokens} tokens")
            ```
        """
        query, params = cls._get_select_query(
            fields=fields,