Skip to content

docs: clarify django style filters #1452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 13, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 45 additions & 4 deletions docs/filter-sort.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,36 @@ Sort can take multiple args, with desc direction added as a (-) prefix
workbooks = workbooks.order_by("project_name", "-created_at")
```

### Indexing and slicing

Querysets can be indexed and sliced like a list. The query is executed at when
the queryset is indexed or sliced.
```py
# Get the first item in the queryset
flow = server.flows.filter(owner_name="admin")[0]

# Get the last item in the queryset
flow = server.flows.filter(owner_name="admin")[-1]

# Get the most recent 10 runs from a flow
runs = server.flow_runs.filter(flow_id=flow.id, page_size=10).order_by("-created_at")[:10]
```

### Supported endpoints

The following endpoints support the Django style filters and sorts:

* Datasources
* Flow Runs
* Flows
* Groups
* Groupsets
* Jobs
* Projects
* Users
* Views
* Workbooks

### More detailed examples

```py
Expand All @@ -147,13 +177,19 @@ workbooks = server.workbooks.all()
# filters can be appended in new lines
workbooks = workbooks.filter(project_name=project_name)

# multiple filters can be added in a single line
workbooks = workbooks.filter(project_name=project_name, owner_name=owner_name, size__gte=1000)

# Multiple filters can be added through chaining.
workbooks = workbooks.filter(project_name=project_name).filter(owner_name=owner_name).filter(size__gte=1000)

# Find all views in a project, with a specific tag
views = server.views.filter(project_name=project_name, tags="stale")

# sort can take multiple args, with desc direction added as a (-) prefix
workbooks = workbooks.order_by("project_name", "-created_at")

# pagination take these two keywords
workbooks = workbooks.paginate(page_size=10, page_number=2)

# query is executed at time of access
# query is executed at time of iteration
for workbook in workbooks:
print(workbook)

Expand All @@ -165,6 +201,11 @@ all_workbooks = server.workbooks.filter(project_name=project_name).order_by("-pr

# operators are implemented using dunderscore
all_workbooks = server.workbooks.filter(project_name__in=["Project A", "Project B"])

# How many items are in the queryset?
flows = server.flows.filter(owner_name="admin")
print(len(flows))

```

### Operators available
Expand Down