Skip to content

rg.Query

To collect records based on searching criteria, you can use the Query and Filter classes. The Query class is used to define the search criteria, while the Filter class is used to filter the search results. Filter is passed to a Query object so you can combine multiple filters to create complex search queries. A Query object can also be passed to Dataset.records to fetch records based on the search criteria.

Usage Examples

Searching for records with terms

To search for records with terms, you can use the Dataset.records attribute with a query string. The search terms are used to search for records that contain the terms in the text field.

for record in dataset.records(query="paris"):
    print(record)

Filtering records by conditions

Argilla allows you to filter records based on conditions. You can use the Filter class to define the conditions and pass them to the Dataset.records attribute to fetch records based on the conditions. Conditions include "==", ">=", "<=", or "in". Conditions can be combined with dot notation to filter records based on metadata, suggestions, or responses.

# create a range from 10 to 20
range_filter = rg.Filter(
    [
        ("metadata.count", ">=", 10),
        ("metadata.count", "<=", 20)
    ]
)

# query records with metadata count greater than 10 and less than 20
query = rg.Query(filters=range_filter, query="paris")

# iterate over the results
for record in dataset.records(query=query):
    print(record)

Query

This class is used to map user queries to the internal query models

Source code in src/argilla/records/_search.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
class Query:
    """This class is used to map user queries to the internal query models"""

    def __init__(
        self,
        *,
        query: Union[str, None] = None,
        similar: Union[Similar, None] = None,
        filter: Union[Filter, Conditions, None] = None,
    ):
        """Create a query object for use in Argilla search requests.add()

        Parameters:
            query (Union[str, None], optional): The query string that will be used to search.
            similar (Union[Similar, None], optional): The similar object that will be used to search for similar records
            filter (Union[Filter, None], optional): The filter object that will be used to filter the search results.
        """

        if isinstance(filter, tuple):
            filter = [filter]

        if isinstance(filter, list):
            filter = Filter(conditions=filter)

        self.query = query
        self.filter = filter
        self.similar = similar

    def has_search(self) -> bool:
        return bool(self.query or self.similar or self.filter)

    def api_model(self) -> SearchQueryModel:
        model = SearchQueryModel()

        if self.query or self.similar:
            query = QueryModel()

            if self.query is not None:
                query.text = TextQueryModel(q=self.query)

            if self.similar is not None:
                query.vector = self.similar.api_model()

            model.query = query

        if self.filter is not None:
            model.filters = self.filter.api_model()

        return model

__init__(*, query=None, similar=None, filter=None)

Create a query object for use in Argilla search requests.add()

Parameters:

Name Type Description Default
query Union[str, None]

The query string that will be used to search.

 None
similar Union[Similar, None]

The similar object that will be used to search for similar records

 None
filter Union[Filter, None]

The filter object that will be used to filter the search results.

 None
Source code in src/argilla/records/_search.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def __init__(
    self,
    *,
    query: Union[str, None] = None,
    similar: Union[Similar, None] = None,
    filter: Union[Filter, Conditions, None] = None,
):
    """Create a query object for use in Argilla search requests.add()

    Parameters:
        query (Union[str, None], optional): The query string that will be used to search.
        similar (Union[Similar, None], optional): The similar object that will be used to search for similar records
        filter (Union[Filter, None], optional): The filter object that will be used to filter the search results.
    """

    if isinstance(filter, tuple):
        filter = [filter]

    if isinstance(filter, list):
        filter = Filter(conditions=filter)

    self.query = query
    self.filter = filter
    self.similar = similar

Filter

This class is used to map user filters to the internal filter models

Source code in src/argilla/records/_search.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
class Filter:
    """This class is used to map user filters to the internal filter models"""

    def __init__(self, conditions: Union[Conditions, None] = None):
        """ Create a filter object for use in Argilla search requests.

        Parameters:
            conditions (Union[List[Tuple[str, str, Any]], Tuple[str, str, Any], None], optional): \
                The conditions that will be used to filter the search results. \
                The conditions should be a list of tuples where each tuple contains \
                the field, operator, and value. For example `("label", "in", ["positive","happy"])`.\
        """

        if isinstance(conditions, tuple):
            conditions = [conditions]
        self.conditions = [Condition(condition) for condition in conditions]

    def api_model(self) -> AndFilterModel:
        return AndFilterModel.model_validate({"and": [condition.api_model() for condition in self.conditions]})

__init__(conditions=None)

Create a filter object for use in Argilla search requests.

Parameters:

Name Type Description Default
conditions Union[List[Tuple[str, str, Any]], Tuple[str, str, Any], None]

The conditions that will be used to filter the search results. The conditions should be a list of tuples where each tuple contains the field, operator, and value. For example ("label", "in", ["positive","happy"]).

 None
Source code in src/argilla/records/_search.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
def __init__(self, conditions: Union[Conditions, None] = None):
    """ Create a filter object for use in Argilla search requests.

    Parameters:
        conditions (Union[List[Tuple[str, str, Any]], Tuple[str, str, Any], None], optional): \
            The conditions that will be used to filter the search results. \
            The conditions should be a list of tuples where each tuple contains \
            the field, operator, and value. For example `("label", "in", ["positive","happy"])`.\
    """

    if isinstance(conditions, tuple):
        conditions = [conditions]
    self.conditions = [Condition(condition) for condition in conditions]

Similar

This class is used to map user similar queries to the internal query models

Source code in src/argilla/records/_search.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
class Similar:
    """This class is used to map user similar queries to the internal query models"""

    def __init__(self, name: str, value: Union[Iterable[float], "Record"], most_similar: bool = True):
        """
        Create a similar object for use in Argilla search requests.

        Parameters:
            name: The name of the vector field
            value: The vector value or the record to search for similar records
            most_similar: Whether to search for the most similar records or the least similar records
        """

        self.name = name
        self.value = value
        self.most_similar = most_similar if most_similar is not None else True

    def api_model(self) -> VectorQueryModel:
        from argilla.records import Record

        order = "most_similar" if self.most_similar else "least_similar"

        if isinstance(self.value, Record):
            return VectorQueryModel(name=self.name, record_id=self.value._server_id, order=order)

        return VectorQueryModel(name=self.name, value=self.value, order=order)

__init__(name, value, most_similar=True)

Create a similar object for use in Argilla search requests.

Parameters:

Name Type Description Default
name str

The name of the vector field

 required
value Union[Iterable[float], Record]

The vector value or the record to search for similar records

 required
most_similar bool

Whether to search for the most similar records or the least similar records

 True
Source code in src/argilla/records/_search.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
def __init__(self, name: str, value: Union[Iterable[float], "Record"], most_similar: bool = True):
    """
    Create a similar object for use in Argilla search requests.

    Parameters:
        name: The name of the vector field
        value: The vector value or the record to search for similar records
        most_similar: Whether to search for the most similar records or the least similar records
    """

    self.name = name
    self.value = value
    self.most_similar = most_similar if most_similar is not None else True