baserow.filter

  1"""
  2Everything related to defining and using filters on data.
  3"""
  4
  5import enum
  6from typing import Optional, Union
  7
  8from typing_extensions import Self
  9from pydantic import BaseModel, ConfigDict, Field
 10
 11
 12class FilterMode(str, enum.Enum):
 13    """
 14    The filter type (also called mode) defines the behavior of the filter,
 15    determining how the filter value is applied to the field. Naming follows the
 16    Baserow UI convention and therefore may differ from the values in some
 17    instances.
 18    """
 19    EQUAL = "equal"
 20    NOT_EQUAL = "not_equal"
 21    DATE_IS = "date_is"
 22    DATE_IS_NOT = "date_is_not"
 23    DATE_IS_BEFORE = "date_is_before"
 24    DATE_IS_ON_OR_BEFORE = "date_is_on_or_before"
 25    DATE_IS_AFTER = "date_is_after"
 26    DATE_IS_ON_OR_AFTER = "date_is_on_or_after"
 27    DATE_IS_WITHIN = "date_is_within"
 28    DATE_EQUALS_DAY_OF_MONTH = "date_equals_day_of_month"
 29    CONTAINS = "contains"
 30    CONTAINS_NOT = "contains_not"
 31    CONTAINS_WORD = "contains_word"
 32    DOESNT_CONTAIN_WORD = "doesnt_contain_word"
 33    FILENAME_CONTAINS = "filename_contains"
 34    HAS_FILE_TYPE = "has_file_type"
 35    FILES_LOWER_THAN = "files_lower_than"
 36    LENGTH_IS_LOWER_THAN = "length_is_lower_than"
 37    HIGHER_THAN = "higher_than"
 38    HIGHER_THAN_OR_EQUAL = "higher_than_or_equal"
 39    LOWER_THAN = "lower_than"
 40    LOWER_THAN_OR_EQUAL = "lower_than_or_equal"
 41    IS_EVEN_AND_WHOLE = "is_even_and_whole"
 42    SINGLE_SELECT_EQUAL = "single_select_equal"
 43    SINGLE_SELECT_NOT_EQUAL = "single_select_not_equal"
 44    SINGLE_SELECT_IS_ANY_OF = "single_select_is_any_of"
 45    SINGLE_SELECT_IS_NONE_OF = "single_select_is_none_of"
 46    BOOLEAN = "boolean"
 47    LINK_ROW_HAS = "link_row_has"
 48    LINK_ROW_HAS_NOT = "link_row_has_not"
 49    LINK_ROW_CONTAINS = "link_row_contains"
 50    LINK_ROW_NOT_CONTAINS = "link_row_not_contains"
 51    MULTIPLE_SELECT_HAS = "multiple_select_has"
 52    MULTIPLE_SELECT_HAS_NOT = "multiple_select_has_not"
 53    MULTIPLE_COLLABORATORS_HAS = "multiple_collaborators_has"
 54    MULTIPLE_COLLABORATORS_HAS_NOT = "multiple_collaborators_has_not"
 55    EMPTY = "empty"
 56    NOT_EMPTY = "not_empty"
 57    USER_IS = "user_is"
 58    USER_IS_NOT = "user_is_not"
 59
 60
 61class Condition(BaseModel):
 62    """
 63    A filter condition is a single filter condition that can be applied to a
 64    field.
 65    """
 66    model_config = ConfigDict(populate_by_name=True)
 67
 68    field: Union[int, str]
 69    """
 70    Field name with `user_field_names`, otherwise field ID as an integer.
 71    """
 72    mode: FilterMode = Field(alias=str("type"))
 73    value: Optional[str]
 74    """The value that the filter should check against."""
 75
 76
 77class Operator(str, enum.Enum):
 78    """
 79    Defines how multiple filter items within a filter interact with each other.
 80    """
 81    AND = "AND"
 82    """All filter items must be true."""
 83    OR = "OR"
 84    """At least one filter item in the filter must be true."""
 85
 86
 87class Filter(BaseModel):
 88    """
 89    A filter tree allows for the construction of complex filter queries. The
 90    object serves as a container for individual filter conditions, all of which
 91    must be true (AND) or at least one must be true (OR).
 92    """
 93    operator: Operator = Field(alias=str("filter_type"))
 94    conditions: list[Condition] = Field(default=[], alias=str("filters"))
 95
 96    def equal(self, field: Union[int, str], value: Optional[str]) -> Self:
 97        """
 98        Retrieve all records where the specified field exactly matches the given
 99        value.
100        """
101        self.conditions.append(
102            Condition(field=field, mode=FilterMode.EQUAL, value=value),
103        )
104        return self
105
106    def not_equal(self, field: Union[int, str], value: Optional[str]) -> Self:
107        """
108        Retrieve all records where the specified field does not match the given
109        value.
110        """
111        self.conditions.append(
112            Condition(field=field, mode=FilterMode.NOT_EQUAL, value=value),
113        )
114        return self
115
116    def contains(self, field: Union[int, str], value: Optional[str]) -> Self:
117        """
118        Retrieve all records where the specified field contains the given value.
119        """
120        self.conditions.append(
121            Condition(field=field, mode=FilterMode.CONTAINS, value=value),
122        )
123        return self
124
125    def date_is(self, field: Union[int, str], value: Optional[str]) -> Self:
126        """
127        Adds a condition with date_is to the filter.
128        """
129        self.conditions.append(
130            Condition(field=field, mode=FilterMode.DATE_IS, value=value),
131        )
132        return self
133
134    def date_is_not(self, field: Union[int, str], value: Optional[str]) -> Self:
135        """
136        Adds a condition with date_is_not to the filter.
137        """
138        self.conditions.append(
139            Condition(field=field, mode=FilterMode.DATE_IS_NOT, value=value),
140        )
141        return self
142
143    def date_is_before(self, field: Union[int, str], value: Optional[str]) -> Self:
144        """
145        Adds a condition with date_is_before to the filter.
146        """
147        self.conditions.append(
148            Condition(field=field, mode=FilterMode.DATE_IS_BEFORE, value=value),
149        )
150        return self
151
152    def date_is_on_or_before(self, field: Union[int, str], value: Optional[str]) -> Self:
153        """
154        Adds a condition with date_is_on_or_before to the filter.
155        """
156        self.conditions.append(
157            Condition(
158                field=field, mode=FilterMode.DATE_IS_ON_OR_BEFORE, value=value),
159        )
160        return self
161
162    def date_is_after(self, field: Union[int, str], value: Optional[str]) -> Self:
163        """
164        Adds a condition with date_is_after to the filter.
165        """
166        self.conditions.append(
167            Condition(field=field, mode=FilterMode.DATE_IS_AFTER, value=value),
168        )
169        return self
170
171    def date_is_on_or_after(self, field: Union[int, str], value: Optional[str]) -> Self:
172        """
173        Adds a condition with date_is_on_or_after to the filter.
174        """
175        self.conditions.append(
176            Condition(
177                field=field, mode=FilterMode.DATE_IS_ON_OR_AFTER, value=value),
178        )
179        return self
180
181    def date_is_within(self, field: Union[int, str], value: Optional[str]) -> Self:
182        """
183        Adds a condition with date_is_within to the filter.
184        """
185        self.conditions.append(
186            Condition(field=field, mode=FilterMode.DATE_IS_WITHIN, value=value),
187        )
188        return self
189
190    def date_equals_day_of_month(self, field: Union[int, str], value: Optional[str]) -> Self:
191        """
192        Adds a condition with date_equals_day_of_month to the filter.
193        """
194        self.conditions.append(
195            Condition(
196                field=field, mode=FilterMode.DATE_EQUALS_DAY_OF_MONTH, value=value),
197        )
198        return self
199
200    def contains_not(self, field: Union[int, str], value: Optional[str]) -> Self:
201        """
202        Retrieve all records where the specified field does not contain the
203        given value.
204        """
205        self.conditions.append(
206            Condition(field=field, mode=FilterMode.CONTAINS_NOT, value=value),
207        )
208        return self
209
210    def contains_word(self, field: Union[int, str], value: Optional[str]) -> Self:
211        """
212        Retrieve all records where the specified field contains the given word.
213        """
214        self.conditions.append(
215            Condition(field=field, mode=FilterMode.CONTAINS_WORD, value=value),
216        )
217        return self
218
219    def doesnt_contain_word(self, field: Union[int, str], value: Optional[str]) -> Self:
220        """
221        Retrieve all records where the specified field does not contain the
222        given word.
223        """
224        self.conditions.append(
225            Condition(
226                field=field, mode=FilterMode.DOESNT_CONTAIN_WORD, value=value),
227        )
228        return self
229
230    def filename_contains(self, field: Union[int, str], value: Optional[str]) -> Self:
231        """
232        Adds a condition with filename_contains to the filter.
233        """
234        self.conditions.append(
235            Condition(field=field, mode=FilterMode.FILENAME_CONTAINS,
236                      value=value),
237        )
238        return self
239
240    def has_file_type(self, field: Union[int, str], value: Optional[str]) -> Self:
241        """
242        Adds a condition with has_file_type to the filter.
243        """
244        self.conditions.append(
245            Condition(field=field, mode=FilterMode.HAS_FILE_TYPE, value=value),
246        )
247        return self
248
249    def files_lower_than(self, field: Union[int, str], value: Optional[str]) -> Self:
250        """
251        Adds a condition with files_lower_than to the filter.
252        """
253        self.conditions.append(
254            Condition(field=field, mode=FilterMode.FILES_LOWER_THAN, value=value),
255        )
256        return self
257
258    def length_is_lower_than(self, field: Union[int, str], value: Optional[str]) -> Self:
259        """
260        Retrieve all records where the specified field does not exceed the given
261        length.
262        """
263        self.conditions.append(
264            Condition(
265                field=field, mode=FilterMode.LENGTH_IS_LOWER_THAN, value=value),
266        )
267        return self
268
269    def higher_than(self, field: Union[int, str], value: Optional[str]) -> Self:
270        """
271        Adds a condition with higher_than to the filter.
272        """
273        self.conditions.append(
274            Condition(field=field, mode=FilterMode.HIGHER_THAN, value=value),
275        )
276        return self
277
278    def higher_than_or_equal(self, field: Union[int, str], value: Optional[str]) -> Self:
279        """
280        Adds a condition with higher_than_or_equal to the filter.
281        """
282        self.conditions.append(
283            Condition(
284                field=field, mode=FilterMode.HIGHER_THAN_OR_EQUAL, value=value),
285        )
286        return self
287
288    def lower_than(self, field: Union[int, str], value: Optional[str]) -> Self:
289        """
290        Adds a condition with lower_than to the filter.
291        """
292        self.conditions.append(
293            Condition(field=field, mode=FilterMode.LOWER_THAN, value=value),
294        )
295        return self
296
297    def lower_than_or_equal(self, field: Union[int, str], value: Optional[str]) -> Self:
298        """
299        Adds a condition with lower_than_or_equal to the filter.
300        """
301        self.conditions.append(
302            Condition(
303                field=field, mode=FilterMode.LOWER_THAN_OR_EQUAL, value=value),
304        )
305        return self
306
307    def is_even_and_whole(self, field: Union[int, str], value: Optional[str]) -> Self:
308        """
309        Adds a condition with is_even_and_whole to the filter.
310        """
311        self.conditions.append(
312            Condition(field=field, mode=FilterMode.IS_EVEN_AND_WHOLE,
313                      value=value),
314        )
315        return self
316
317    def single_select_equal(self, field: Union[int, str], value: Optional[str]) -> Self:
318        """
319        Adds a condition with single_select_equal to the filter.
320        """
321        self.conditions.append(
322            Condition(
323                field=field, mode=FilterMode.SINGLE_SELECT_EQUAL, value=value),
324        )
325        return self
326
327    def single_select_not_equal(self, field: Union[int, str], value: Optional[str]) -> Self:
328        """
329        Adds a condition with single_select_not_equal to the filter.
330        """
331        self.conditions.append(
332            Condition(
333                field=field, mode=FilterMode.SINGLE_SELECT_NOT_EQUAL, value=value),
334        )
335        return self
336
337    def single_select_is_any_of(self, field: Union[int, str], value: Optional[str]) -> Self:
338        """
339        Adds a condition with single_select_is_any_of to the filter.
340        """
341        self.conditions.append(
342            Condition(
343                field=field, mode=FilterMode.SINGLE_SELECT_IS_ANY_OF, value=value),
344        )
345        return self
346
347    def single_select_is_none_of(self, field: Union[int, str], value: Optional[str]) -> Self:
348        """
349        Adds a condition with single_select_is_none_of to the filter.
350        """
351        self.conditions.append(
352            Condition(
353                field=field, mode=FilterMode.SINGLE_SELECT_IS_NONE_OF, value=value),
354        )
355        return self
356
357    def boolean(self, field: Union[int, str], value: Optional[str]) -> Self:
358        """
359        Adds a condition with boolean to the filter.
360        """
361        self.conditions.append(
362            Condition(field=field, mode=FilterMode.BOOLEAN, value=value),
363        )
364        return self
365
366    def link_row_has(self, field: Union[int, str], value: Optional[str]) -> Self:
367        """
368        Adds a condition with link_row_has to the filter.
369        """
370        self.conditions.append(
371            Condition(field=field, mode=FilterMode.LINK_ROW_HAS, value=value),
372        )
373        return self
374
375    def link_row_has_not(self, field: Union[int, str], value: Optional[str]) -> Self:
376        """
377        Adds a condition with link_row_has_not to the filter.
378        """
379        self.conditions.append(
380            Condition(field=field, mode=FilterMode.LINK_ROW_HAS_NOT, value=value),
381        )
382        return self
383
384    def link_row_contains(self, field: Union[int, str], value: Optional[str]) -> Self:
385        """
386        Adds a condition with link_row_contains to the filter.
387        """
388        self.conditions.append(
389            Condition(field=field, mode=FilterMode.LINK_ROW_CONTAINS,
390                      value=value),
391        )
392        return self
393
394    def link_row_not_contains(self, field: Union[int, str], value: Optional[str]) -> Self:
395        """
396        Adds a condition with link_row_not_contains to the filter.
397        """
398        self.conditions.append(
399            Condition(
400                field=field, mode=FilterMode.LINK_ROW_NOT_CONTAINS, value=value),
401        )
402        return self
403
404    def multiple_select_has(self, field: Union[int, str], value: Optional[str]) -> Self:
405        """
406        Adds a condition with multiple_select_has to the filter.
407        """
408        self.conditions.append(
409            Condition(
410                field=field, mode=FilterMode.MULTIPLE_SELECT_HAS, value=value),
411        )
412        return self
413
414    def multiple_select_has_not(self, field: Union[int, str], value: Optional[str]) -> Self:
415        """
416        Adds a condition with multiple_select_has_not to the filter.
417        """
418        self.conditions.append(
419            Condition(
420                field=field, mode=FilterMode.MULTIPLE_SELECT_HAS_NOT, value=value),
421        )
422        return self
423
424    def multiple_collaborators_has(self, field: Union[int, str], value: Optional[str]) -> Self:
425        """
426        Adds a condition with multiple_collaborators_has to the filter.
427        """
428        self.conditions.append(
429            Condition(
430                field=field, mode=FilterMode.MULTIPLE_COLLABORATORS_HAS, value=value),
431        )
432        return self
433
434    def multiple_collaborators_has_not(self, field: Union[int, str], value: Optional[str]) -> Self:
435        """
436        Adds a condition with multiple_collaborators_has_not to the filter.
437        """
438        self.conditions.append(
439            Condition(
440                field=field, mode=FilterMode.MULTIPLE_COLLABORATORS_HAS_NOT, value=value),
441        )
442        return self
443
444    def empty(self, field: Union[int, str], value: Optional[str]) -> Self:
445        """
446        Retrieve all records that are empty.
447        """
448        self.conditions.append(
449            Condition(field=field, mode=FilterMode.EMPTY, value=value),
450        )
451        return self
452
453    def not_empty(self, field: Union[int, str], value: Optional[str]) -> Self:
454        """
455        Retrieve all records that are not empty.
456        """
457        self.conditions.append(
458            Condition(field=field, mode=FilterMode.NOT_EMPTY, value=value),
459        )
460        return self
461
462    def user_is(self, field: Union[int, str], value: Optional[str]) -> Self:
463        """
464        Adds a condition with user_is to the filter.
465        """
466        self.conditions.append(
467            Condition(field=field, mode=FilterMode.USER_IS, value=value),
468        )
469        return self
470
471    def user_is_not(self, field: Union[int, str], value: Optional[str]) -> Self:
472        """
473        Adds a condition with user_is_not to the filter.
474        """
475        self.conditions.append(
476            Condition(field=field, mode=FilterMode.USER_IS_NOT, value=value),
477        )
478        return self
479
480
481class AndFilter(Filter):
482    """
483    A filter tree allows for the construction of complex filter queries. The
484    object serves as a container for individual filter conditions, all of which
485    must be true (AND filter).
486    """
487    operator: Operator = Field(
488        default=Operator.AND, alias=str("filter_type"), frozen=True)
489
490
491class OrFilter(Filter):
492    """
493    A filter tree allows for the construction of complex filter queries. The
494    object serves as a container for individual filter conditions, all of any
495    can be true (OR filter).
496    """
497    operator: Operator = Field(
498        default=Operator.OR, alias=str("filter_type"), frozen=True)