prisma-client-api-query-options

用途

本资料是 Prisma Client API 中 Query Options（查询选项）的参考，用于说明在调用 Prisma 查询时可通过哪些选项控制查询行为与返回结果。适用于使用 Prisma 功能时需要查阅常见写法的场景。

主要能力

select

选择要返回的特定字段：

const user = await prisma.user.findUnique({
  where: { id: 1 },
  select: {
    id: true,
    name: true,
    email: true,
    // password: false (excluded by not including)
  }
})
// Returns: { id: 1, name: 'Alice', email: 'alice@prisma.io' }

选择关联：

const user = await prisma.user.findUnique({
  where: { id: 1 },
  select: {
    name: true,
    posts: {
      select: {
        title: true,
        published: true
      }
    }
  }
})

在 select 内部使用 include：

const user = await prisma.user.findMany({
  select: {
    name: true,
    posts: {
      include: {
        comments: true
      }
    }
  }
})

选择关联计数：

const users = await prisma.user.findMany({
  select: {
    name: true,
    _count: {
      select: { posts: true }
    }
  }
})
// Returns: { name: 'Alice', _count: { posts: 5 } }

include

包含关联记录：

const user = await prisma.user.findUnique({
  where: { id: 1 },
  include: {
    posts: true,
    profile: true
  }
})

带过滤的 include：

const user = await prisma.user.findUnique({
  where: { id: 1 },
  include: {
    posts: {
      where: { published: true },
      orderBy: { createdAt: 'desc' },
      take: 5
    }
  }
})

嵌套 include：

const user = await prisma.user.findUnique({
  where: { id: 1 },
  include: {
    posts: {
      include: {
        comments: {
          include: {
            author: true
          }
        }
      }
    }
  }
})

包含关联计数：

const users = await prisma.user.findMany({
  include: {
    _count: {
      select: { posts: true, followers: true }
    }
  }
})

omit

排除特定字段：

const user = await prisma.user.findUnique({
  where: { id: 1 },
  omit: {
    password: true
  }
})
// Returns all fields except password

在关联中使用 omit：

const users = await prisma.user.findMany({
  omit: { password: true },
  include: {
    posts: {
      omit: { content: true }
    }
  }
})

注意：select 和 omit 不能一起使用。

where

过滤记录：

const users = await prisma.user.findMany({
  where: {
    email: { contains: '@prisma.io' },
    role: 'ADMIN'
  }
})

详细过滤操作符见 filters.md。

orderBy

排序结果：

// Single field
const users = await prisma.user.findMany({
  orderBy: { name: 'asc' }
})

// Multiple fields
const users = await prisma.user.findMany({
  orderBy: [
    { role: 'desc' },
    { name: 'asc' }
  ]
})

按关联排序：

const users = await prisma.user.findMany({
  orderBy: {
    posts: { _count: 'desc' }
  }
})

空值处理：

const users = await prisma.user.findMany({
  orderBy: {
    name: { sort: 'asc', nulls: 'last' }
  }
})

take 与 skip

分页：

// First page
const users = await prisma.user.findMany({
  take: 10,
  skip: 0
})

// Second page
const users = await prisma.user.findMany({
  take: 10,
  skip: 10
})

负 take（反向）：

const lastUsers = await prisma.user.findMany({
  take: -10,
  orderBy: { id: 'asc' }
})
// Returns last 10 users

cursor

基于游标的分页：

// First page
const firstPage = await prisma.user.findMany({
  take: 10,
  orderBy: { id: 'asc' }
})

// Next page using cursor
const nextPage = await prisma.user.findMany({
  take: 10,
  skip: 1,  // Skip the cursor record
  cursor: { id: firstPage[firstPage.length - 1].id },
  orderBy: { id: 'asc' }
})

distinct

返回唯一值：

const cities = await prisma.user.findMany({
  distinct: ['city'],
  select: { city: true }
})

多个 distinct 字段：

const locations = await prisma.user.findMany({
  distinct: ['city', 'country']
})

使用方式

以上示例均通过 Prisma Client 的查询方法（如 findUnique、findMany）传入对应选项来使用。调用方式与字段命名以实际代码示例为准。

适用场景

适合在使用 Prisma 进行数据查询时，需要控制返回字段、加载关联、过滤排序或分页去重的开发场景。

限制

资料明确提示：select 与 omit 不能同时使用。关于过滤操作符的完整说明，资料指向 filters.md。其余关于平台、价格、安装步骤等信息暂未提供。