Skip to content

Cleanup in expression-dsl.md #2168

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.

Sign up for GitHub

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
kevinjqliu merged 1 commit into from
Jul 6, 2025
Merged

Cleanup in expression-dsl.md #2168

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 3 additions & 18 deletions mkdocs/docs/expression-dsl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@

# Expression DSL

The PyIceberg library provides a powerful expression DSL (Domain Specific Language) for building complex row filter expressions. This guide will help you understand how to use the expression DSL effectively. This DSL allows you to build type-safe expressions for use in the `row_filter` scan argument.
The PyIceberg library provides a powerful expression Domain Specific Language (DSL) for building complex row filter expressions. This guide will help you understand how to use the expression DSL effectively. This DSL allows you to build type-safe expressions for use in the `row_filter` scan argument.

They are composed of terms, predicates, and logical operators.

Expand Down Expand Up @@ -151,20 +151,6 @@ age_in_range = Not(
)
```

### Type Safety
Copy link
Contributor Author

@Fokko Fokko Jul 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is confusing, since this is allowed:

image


The expression DSL provides type safety through Python's type system. When you create expressions, the types are checked at runtime:

```python
from pyiceberg.expressions import EqualTo

# This will work
age_equals_18 = EqualTo("age", 18)

# This will raise a TypeError if the field type doesn't match
age_equals_18 = EqualTo("age", "18") # Will fail if age is an integer field
```

## Best Practices

1. **Use Type Hints**: Always use type hints when working with expressions to catch type-related errors early.
Expand Down Expand Up @@ -204,7 +190,7 @@ complex_filter = And(age_range, status_filter)
- `IsNull` (and `IsNaN` for doubles/floats) on a required field will always return `False`
- `NotNull` (and `NotNaN` for doubles/floats) on a required field will always return `True`

2. **String Comparisons**: When using string predicates like `StartsWith`, ensure that the field type is actually a string type.
2. **String Comparisons**: When using string predicates like `StartsWith`, ensure that the field type is a string type.

## Examples

Expand All @@ -213,7 +199,6 @@ Here are some practical examples of using the expression DSL:
### Basic Filtering

```python

from datetime import datetime
from pyiceberg.expressions import (
And,
Expand Down Expand Up @@ -256,4 +241,4 @@ complex_filter = And(
EqualTo("type", "enterprise")
)
)
```
```