ZTeraDB Filter Conditions

This guide explains all filter functions in ZTeraDB in the simplest possible way.
Filters allow you to build powerful conditions like:

• a = b
• a > b
• price * quantity > 100
• name contains "abc"
• age in [20, 30]

Every filter returns a FilterCondition object, which you pass into:

query.filterCondition(condition)

---

🎯 Types of Filters

ZTeraDB supports 4 categories:

1. Comparison Filters
2. Math Filters
3. String Filters
4. Logical Filters

To use filters:

from zteradb.filter_condition import *

Each example below includes a simple SQL equivalent for clarity.

---

1️⃣ Comparison Filters

🟩 ZTEQUAL(a, b)

Checks if a = b.

ZTEQUAL("age", 25)
ZTEQUAL(ZTMUL(["price", 2]), 100)

SQL Equivalent

age = 25;
(price * 2) = 100;

---

🟦 ZTGT([a, b])

Checks if a > b.

ZTGT(["age", 18])
ZTGT(["price", ZTMUL(["discount", 2])])

SQL Equivalent

age > 18;
price > (discount * 2);

---

🟪 ZTGTE([a, b])

Checks if a ≥ b.

ZTGTE(["salary", 40000])

SQL Equivalent

salary >= 40000;

---

🟧 ZTLT([a, b])

Checks if a < b.

ZTLT(["age", 65])

SQL Equivalent

age < 65;

---

🟫 ZTLTE([a, b])

Checks if a ≤ b.

ZTLTE(["rating", 5])

SQL Equivalent

rating <= 5;

---

🟨 ZTIN(field, [values])

Checks if field IN (values).

ZTIN("age", [20, 25, 30])

SQL Equivalent

age IN (20, 25, 30);

---

2️⃣ Math Filters

These allow calculations inside filters.

➕ ZTADD([a, b, c])

a + b + c

ZTEQUAL(ZTADD(["price", 50]), 150)

SQL Equivalent

(price + 50) = 150;

---

➖ ZTSUB([a, b])

a - b

ZTSUB(["price", "discount"])

SQL Equivalent

(price - discount);

---

✖ ZTMUL([a, b])

a * b

ZTEQUAL(ZTMUL(["a", "b"]), 10)

SQL Equivalent

(a * b) = 10;

---

➗ ZTDIV(a, b)

a ÷ b

ZTDIV("price", 2)

SQL Equivalent

(price / 2);

---

🔢 ZTMOD(a, b)

a % b

ZTEQUAL(ZTMOD("id", 2), 0)  # even numbers

SQL Equivalent

(id % 2) = 0;

---

3️⃣ String Filters

🔍 ZTCONTAINS(field, value)

Case-sensitive search.

ZTCONTAINS("name", "Tea")

SQL Equivalent

name LIKE '%Tea%';

---

🔍 ZTICONTAINS(field, value)

Case-insensitive search.

ZTICONTAINS("name", "john")

SQL Equivalent

LOWER(name) LIKE '%john%';

---

🟦 ZTSTARTSWITH(field, value)

Case-sensitive “starts with”.

ZTSTARTSWITH("product_name", "A")

SQL Equivalent

product_name LIKE 'A%';

---

🟦 ZTISTARTSWITH(field, value)

Case-insensitive.

ZTISTARTSWITH("product_name", "a")

SQL Equivalent

LOWER(product_name) LIKE 'a%';

---

🟩 ZTENDSWITH(field, value)

Case-sensitive “ends with”.

ZTENDSWITH("tag", "pro")

SQL Equivalent

tag LIKE '%pro';

---

🟩 ZTIENDSWITH(field, value)

Case-insensitive.

ZTIENDSWITH("tag", "PRO")

SQL Equivalent

LOWER(tag) LIKE '%pro';

---

4️⃣ Logical Filters

Combine multiple conditions.

---

🟢 ZTAND([condition1, condition2])

All conditions must be true.

ZTAND([
    ZTGTE(["age", 18]),
    ZTLT(["age", 30])
])

SQL Equivalent

(age >= 18) AND (age < 30);

---

🔴 ZTOR([condition1, condition2])

At least one condition must be true.

ZTOR([
    ZTEQUAL("status", "A"),
    ZTEQUAL("status", "D")
])

SQL Equivalent

(status = 'A') OR (status = 'D');

---

🧪 Full Practical Example

Get all products where price * quantity > 500 AND name contains "wire".

fc = ZTAND([
    ZTGT([ZTMUL(["price", "quantity"]), 500]),
    ZTICONTAINS("name", "wire")
])

query = (
    ZTeraDBQuery("product")
    .select()
    .filterCondition(fc)
)

SQL Equivalent

SELECT *
FROM product
WHERE (price * quantity) > 500
  AND LOWER(name) LIKE '%wire%';

---

⚠ Common Mistakes (and fixes)

Mistake	Fix
Passing single value instead of array in math filters	Always pass lists like ["a", "b"]
Using .filter() for advanced logic	Use .filterCondition()
Incorrect casing in string filters	Use ZTICONTAINS for safer matches
Empty conditions	Always provide at least one filter

---

🎉 You now understand all ZTeraDB filter functions — and their SQL equivalents!

Continue to:
👉 query-examples.md