ormar/docs/queries/raw-data.md

Return raw data

Following methods allow you to execute a query but instead of returning ormar models those will return list of dicts or tuples.

• values(fields = None, exclude_through = False) -> List[Dict]

• values_list(fields = None, exclude_through = False, flatten = False) -> List

• QuerysetProxy

  • QuerysetProxy.values(fields = None, exclude_through = False) method
  • QuerysetProxy.values_list(fields = None, exclude_through= False, flatten = False) method

!!!danger Note that values and values_list skips parsing the result to ormar models so skips also the validation of the result!

!!!warning Note that each entry in a result list is one to one reflection of a query result row. Since rows are not parsed if you have one-to-many or many-to-many relation expect duplicated columns values in result entries if one parent row have multiple related rows.

values

values(fields: Union[List, str, Set, Dict] = None, exclude_through: bool = False) -> List[Dict]

Return a list of dictionaries representing the values of the columns coming from the database.

You can select a subset of fields with fields parameter, that accepts the same set of parameters as fields() method.

Note that passing fields to values(fields) is actually a shortcut for calling fields(fields).values().

!!!tip To read more about what you can pass to fields and how to select nested models fields read selecting columns docs

You can limit the number of rows by providing conditions in filter() and exclude(), but note that even if only one row (or no rows!) match your criteria you will return a list in response.

Example:

# declared models

class Category(ormar.Model):
    class Meta(BaseMeta):
        tablename = "categories"

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=40)
    sort_order: int = ormar.Integer(nullable=True)


class Post(ormar.Model):
    class Meta(BaseMeta):
        tablename = "posts"

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=200)
    category: Optional[Category] = ormar.ForeignKey(Category)

# sample data
news = await Category(name="News", sort_order=0).save()
await Post(name="Ormar strikes again!", category=news).save()
await Post(name="Why don't you use ormar yet?", category=news).save()
await Post(name="Check this out, ormar now for free", category=news).save()

Access Post models:

posts = await Post.objects.values()
assert posts == [
    {"id": 1, "name": "Ormar strikes again!", "category": 1},
    {"id": 2, "name": "Why don't you use ormar yet?", "category": 1},
    {"id": 3, "name": "Check this out, ormar now for free", "category": 1},
]

To select also related models use select_related or prefetch_related.

Note how nested models columns will be prefixed with full relation path coming from the main model (the one used in a query).

# declare models

class User(ormar.Model):
    class Meta(BaseMeta):
        pass

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=100)


class Role(ormar.Model):
    class Meta(BaseMeta):
        pass

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=100)
    users: List[User] = ormar.ManyToMany(User)

# sample data
creator = await User(name="Anonymous").save()
admin = await Role(name="admin").save()
editor = await Role(name="editor").save()
await creator.roles.add(admin)
await creator.roles.add(editor)

Select user with roles

user = await User.objects.select_related("roles").values()
# note nested prefixes: roleuser and roles
assert user == [
    {
        "id": 1,
        "name": "Anonymous",
        "roleuser__id": 1,
        "roleuser__role": 1,
        "roleuser__user": 1,
        "roles__id": 1,
        "roles__name": "admin",
    },
    {
        "id": 1,
        "name": "Anonymous",
        "roleuser__id": 2,
        "roleuser__role": 2,
        "roleuser__user": 1,
        "roles__id": 2,
        "roles__name": "editor",
    },
]

!!!note Note how role to users relation is a ManyToMany relation so by default you also get through model columns.

Combine select related and fields to select only 3 fields.

Note that we also exclude through model as by definition every model included in a join but without any reference in fields is assumed to be selected in full (all fields included).

!!!note Note that in contrary to other queryset methods here you can exclude the in-between models but keep the end columns, which does not make sense when parsing the raw data into models.

So in relation category -> category_x_post -> post -> user you can exclude
category_x_post and post models but can keep the user one. (in ormar model
context that is not possible as if you would exclude through and post model
there would be no way to reach user model from category model).

user = (
        await Role.objects.select_related("users__categories")
        .filter(name="admin")
        .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}})
        .exclude_fields("roleuser")
        .values()
    )
assert user == [
    {
        "name": "admin",
        "users__name": "Anonymous",
        "users__categories__name": "News",
    }
]

If you have multiple ManyToMany models in your query you would have to exclude each through model manually.

To avoid this burden ormar provides you with exclude_through=False parameter. If you set this flag to True all through models will be fully excluded.

# equivalent to query above, note lack of exclude_fields call
user = (
    await Role.objects.select_related("users__categories")
    .filter(name="admin")
    .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}})
    .values(exclude_through=True)
)
assert user == [
    {
        "name": "admin",
        "users__name": "Anonymous",
        "users__categories__name": "News",
    }
]

values_list

values_list(fields: Union[List, str, Set, Dict] = None, flatten: bool = False, exclude_through: bool = False) -> List

Return a list of tuples representing the values of the columns coming from the database.

You can select a subset of fields with fields parameter, that accepts the same set of parameters as fields() method.

Note that passing fields to values_list(fields) is actually a shortcut for calling fields(fields).values_list().

!!!tip To read more about what you can pass to fields and how to select nested models fields read selecting columns docs

If you select only one column/field you can pass flatten=True which will return you a list of values instead of list of one element tuples.

!!!warning Setting flatten=True if more than one (or none which means all) fields are selected will raise QueryDefinitionError exception.

You can limit the number of rows by providing conditions in filter() and exclude(), but note that even if only one row (or no rows!) match your criteria you will return a list in response.

Example:

# declared models

class Category(ormar.Model):
    class Meta(BaseMeta):
        tablename = "categories"

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=40)
    sort_order: int = ormar.Integer(nullable=True)


class Post(ormar.Model):
    class Meta(BaseMeta):
        tablename = "posts"

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=200)
    category: Optional[Category] = ormar.ForeignKey(Category)

# sample data
news = await Category(name="News", sort_order=0).save()
await Post(name="Ormar strikes again!", category=news).save()
await Post(name="Why don't you use ormar yet?", category=news).save()
await Post(name="Check this out, ormar now for free", category=news).save()

Access Post models:

posts = await Post.objects.values_list()
# note how columns refer to id, name and category (fk)
assert posts == [
    (1, "Ormar strikes again!", 1),
    (2, "Why don't you use ormar yet?", 1),
    (3, "Check this out, ormar now for free", 1),
]

To select also related models use select_related or prefetch_related.

Let's complicate the relation and modify the previously mentioned Category model to refer to User model.

class Category(ormar.Model):
    class Meta(BaseMeta):
        tablename = "categories"

    id: int = ormar.Integer(primary_key=True)
    name: str = ormar.String(max_length=40)
    sort_order: int = ormar.Integer(nullable=True)
    # new column below
    created_by: Optional[User] = ormar.ForeignKey(User, related_name="categories")

Now create the sample data with link to user.

creator = await User(name="Anonymous").save()
admin = await Role(name="admin").save()
editor = await Role(name="editor").save()
await creator.roles.add(admin)
await creator.roles.add(editor)
news = await Category(name="News", sort_order=0, created_by=creator).save()

Combine select related and fields to select only 3 fields.

Note that we also exclude through model as by definition every model included in a join but without any reference in fields is assumed to be selected in full (all fields included).

!!!note Note that in contrary to other queryset methods here you can exclude the in-between models but keep the end columns, which does not make sense when parsing the raw data into models.

So in relation category -> category_x_post -> post -> user you can exclude
category_x_post and post models but can keep the user one. (in ormar model
context that is not possible as if you would exclude through and post model
there would be no way to reach user model from category model).

user = (
        await Role.objects.select_related("users__categories")
        .filter(name="admin")
        .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}})
        .exclude_fields("roleuser")
        .values_list()
    )
assert user == [("admin", "Anonymous", "News")]

If you have multiple ManyToMany models in your query you would have to exclude each through model manually.

To avoid this burden ormar provides you with exclude_through=False parameter. If you set this flag to True all through models will be fully excluded.

# equivalent to query above, note lack of exclude_fields call
user = (
        await Role.objects.select_related("users__categories")
        .filter(name="admin")
        .fields({"name": ..., "users": {"name": ..., "categories": {"name"}}})
        .values_list(exclude_through=True)
    )
assert user == [("admin", "Anonymous", "News")]

Use flatten to get list of values.

# using flatten with more than one field will raise exception!
await Role.objects.fields({"name", "id"}).values_list(flatten=True)

# proper usage
roles = await Role.objects.fields("name").values_list(flatten=True)
assert roles == ["admin", "editor"]

QuerysetProxy methods

When access directly the related ManyToMany field as well as ReverseForeignKey returns the list of related models.

But at the same time it exposes subset of QuerySet API, so you can filter, create, select related etc related models directly from parent model.

!!!warning Because using values and values_list skips parsing of the models and validation, in contrast to all other read methods in querysetproxy those 2 does not clear currently loaded related models and does not overwrite the currently loaded models with result of own call!

values

Works exactly the same as values function above but allows you to fetch related objects from other side of the relation.

!!!tip To read more about QuerysetProxy visit [querysetproxy][querysetproxy] section

values_list

Works exactly the same as values_list function above but allows you to query or create related objects from other side of the relation.

!!!tip To read more about QuerysetProxy visit [querysetproxy][querysetproxy] section