返回原始数据

以下方法允许您执行查询，但不会返回 ormar 模型，而是返回字典或元组列表。

values(fields = None, exclude_through = False) -> List[Dict]
values_list(fields = None, exclude_through = False, flatten = False) -> List
查询集代理
- QuerysetProxy.values(fields = None, exclude_through = False) 方法
- QuerysetProxy.values_list(fields = None, exclude_through= False, flatten = False) 方法

!!!danger 请注意，values 和values_list 会跳过将结果解析为ormar 模型，因此也会跳过结果的验证！

!!!警告请注意，结果列表中的每个条目都是查询结果行的一对一反映。由于如果您具有一对多或多对多关系，则不会解析行，因此如果一个父行具有多个相关行，则结果条目中会出现重复的列值。

价值观

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

返回表示来自数据库的列的值的字典列表。

您可以使用 fields 参数选择字段的子集，该子集接受与 fields() 方法相同的参数集。

请注意，将字段传递给values(fields)实际上是调用fields(fields).values()的快捷方式。

!!!tip 要了解有关可以传递给字段的内容以及如何选择嵌套模型字段的更多信息，请阅读选择列文档

您可以通过在 filter() 和 except() 中提供条件来限制行数，但请注意，即使只有一行（或没有行！）符合您的条件，您也会返回一个列表作为响应。

例子：

# declared models

class Category(ormar.Model):
    ormar_config = base_ormar_config.copy(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):
    ormar_config = base_ormar_config.copy()

    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()

访问邮政模型：

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},
]

要同时选择相关模型，请使用 select_lated 或 prefetch_lated。

请注意嵌套模型列如何以来自主模型（查询中使用的模型）的完整关系路径为前缀。

# declare models

class User(ormar.Model):
    ormar_config = base_ormar_config.copy()

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


class Role(ormar.Model):
    ormar_config = base_ormar_config.copy()

    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)

选择具有角色的用户

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 请注意角色与用户的关系是多对多关系，因此默认情况下您还可以获取模型列。

组合选择相关字段和字段以仅选择 3 个字段。

请注意，我们还通过模型排除了定义，因为根据定义，连接中包含的每个模型但在字段中没有任何引用的模型都被假定为完全选择（包括所有字段）。

!!!note 请注意，与此处的其他查询集方法相反，您可以排除中间模型但保留末尾列，这在将原始数据解析为模型时没有意义。

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",
    }
]

如果查询中有多个 ManyToMany 模型，则必须手动排除每个模型。

为了避免这种负担，ormar 为您提供了 except_through=False 参数。如果将此标志设置为 True，所有模型都将被完全排除。

# 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(fields: Union[List, str, Set, Dict] = None, flatten: bool = False, exclude_through: bool = False) -> List

返回表示来自数据库的列的值的元组列表。

您可以使用 fields 参数选择字段的子集，该子集接受与 fields() 方法相同的参数集。

请注意，将字段传递给values_list(fields)实际上是调用fields(fields).values_list()的快捷方式。

!!!tip 要了解有关可以传递给字段的内容以及如何选择嵌套模型字段的更多信息，请阅读选择列文档

如果您只选择一列/字段，您可以传递 flatten=True ，这将返回一个值列表，而不是一个元素元组的列表。

!!!警告如果选择多个（或没有，即表示所有）字段，则设置 flatten=True 将引发 QueryDefinitionError 异常。

您可以通过在 filter() 和 except() 中提供条件来限制行数，但请注意，即使只有一行（或没有行！）符合您的条件，您也会返回一个列表作为响应。

例子：

# declared models

class Category(ormar.Model):
    ormar_config = base_ormar_config.copy(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):
    ormar_config = base_ormar_config.copy()

    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()

访问邮政模型：

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),
]

要同时选择相关模型，请使用 select_lated 或 prefetch_lated。

让我们使关系复杂化并修改前面提到的类别模型以引用用户模型。

class Category(ormar.Model):
    ormar_config = base_ormar_config.copy(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")

现在创建带有用户链接的示例数据。

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()

组合选择相关字段和字段以仅选择 3 个字段。

请注意，我们还通过模型排除了定义，因为根据定义，连接中包含的每个模型但在字段中没有任何引用的模型都被假定为完全选择（包括所有字段）。

!!!note 请注意，与此处的其他查询集方法相反，您可以排除中间模型但保留末尾列，这在将原始数据解析为模型时没有意义。

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")]

如果查询中有多个 ManyToMany 模型，则必须手动排除每个模型。

为了避免这种负担，ormar 为您提供了 except_through=False 参数。如果将此标志设置为 True，所有模型都将被完全排除。

# 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")]

使用 flatten 获取值列表。

# 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 方法

当直接访问相关的ManyToMany字段以及ReverseForeignKey时，返回相关模型的列表。

但同时它公开了 QuerySet API 的子集，因此您可以直接从父模型过滤、创建、选择相关模型等。

!!!警告因为使用values和values_list会跳过模型的解析和验证，与querysetproxy中的所有其他读取方法相比，这2个方法不会清除当前加载的相关模型，并且不会用自己的调用结果覆盖当前加载的模型！

价值观

与上面的值函数完全相同，但允许您从关系的另一端获取相关对象。

!!!tip 要了解有关 QuerysetProxy 的更多信息，请访问 querysetproxy 部分

值列表

与上面的 value_list 函数完全相同，但允许您从关系的另一端查询或创建相关对象。

!!!tip 要了解有关 QuerysetProxy 的更多信息，请访问 querysetproxy 部分