diff --git a/docs/tutorial/where.md b/docs/tutorial/where.md index ca85a4dd00..e5406cbab8 100644 --- a/docs/tutorial/where.md +++ b/docs/tutorial/where.md @@ -665,7 +665,7 @@ age=32 id=4 name='Tarantula' secret_name='Natalia Roman-on' ### Less Than or Equal -Finally, we can use `<=` to get the rows where a column is **less than or equal** to a value: +We can also use `<=` to get the rows where a column is **less than or equal** to a value: ```Python hl_lines="5" # Code above omitted 👆 @@ -694,6 +694,34 @@ age=35 id=5 name='Black Lion' secret_name='Trevor Challa' !!! tip We get `Black Lion` here too because although the age is not *strictly* less than `35` it is *equal* to `35`. +### In + +Finally, we can use `in_ to get the rows where a column is a member of a collection of values: + +```Python hl_lines="5" +# Code above omitted 👆 + +{!./docs_src/tutorial/where/tutorial0066.py[ln:44-49]!} + +# Code below omitted 👇 +``` + +
+👀 Full file preview + +```Python +{!./docs_src/tutorial/where/tutorial0065.py!} +``` + +
+ +In this case, we match `Deadpond` since it's part of the collections of names. +We don't have any hero called `Ratman`, so it does not match any hero. + +!!! tip + You need to wrap your attribute with `col()` to use `in_`. + You can read more about it in the (Type annotations and errors)[#type-annotations-and-errors] section. + ### Benefits of Expressions Here's a good moment to see that being able to use these pure Python expressions instead of keyword arguments can help a lot. ✨ diff --git a/docs_src/tutorial/where/tutorial0065.py b/docs_src/tutorial/where/tutorial0065.py new file mode 100644 index 0000000000..deb0b23025 --- /dev/null +++ b/docs_src/tutorial/where/tutorial0065.py @@ -0,0 +1,59 @@ +from typing import Optional + +from sqlmodel import Field, Session, SQLModel, col, create_engine, select + + +class Hero(SQLModel, table=True): + id: Optional[int] = Field(default=None, primary_key=True) + name: str + secret_name: str + age: Optional[int] = None + + +sqlite_file_name = "database.db" +sqlite_url = f"sqlite:///{sqlite_file_name}" + +engine = create_engine(sqlite_url, echo=True) + + +def create_db_and_tables(): + SQLModel.metadata.create_all(engine) + + +def create_heroes(): + hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson") + hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador") + hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48) + hero_4 = Hero(name="Tarantula", secret_name="Natalia Roman-on", age=32) + hero_5 = Hero(name="Black Lion", secret_name="Trevor Challa", age=35) + hero_6 = Hero(name="Dr. Weird", secret_name="Steve Weird", age=36) + hero_7 = Hero(name="Captain North America", secret_name="Esteban Rogelios", age=93) + + with Session(engine) as session: + session.add(hero_1) + session.add(hero_2) + session.add(hero_3) + session.add(hero_4) + session.add(hero_5) + session.add(hero_6) + session.add(hero_7) + + session.commit() + + +def select_heroes(): + with Session(engine) as session: + statement = select(Hero).where(col(Hero.name).in_(["Deadpond", "Ratman"])) + results = session.exec(statement) + for hero in results: + print(hero) + + +def main(): + create_db_and_tables() + create_heroes() + select_heroes() + + +if __name__ == "__main__": + main() diff --git a/tests/test_tutorial/test_where/test_tutorial0065.py b/tests/test_tutorial/test_where/test_tutorial0065.py new file mode 100644 index 0000000000..675b3fdc2f --- /dev/null +++ b/tests/test_tutorial/test_where/test_tutorial0065.py @@ -0,0 +1,28 @@ +from unittest.mock import patch + +from sqlmodel import create_engine + +from ...conftest import get_testing_print_function + + +def test_tutorial(clear_sqlmodel): + from docs_src.tutorial.where import tutorial0065 as mod + + mod.sqlite_url = "sqlite://" + mod.engine = create_engine(mod.sqlite_url) + calls = [] + + new_print = get_testing_print_function(calls) + + with patch("builtins.print", new=new_print): + mod.main() + assert calls == [ + [ + { + "name": "Deadpond", + "secret_name": "Dive Wilson", + "age": None, + "id": 1, + } + ] + ]