prisma-client-api

Prisma Client API 參考文件

完整的 Prisma Client API 參考文件。此技能提供模型查詢、篩選、關聯及客戶端方法的指引，適用於目前的 Prisma 專案。

適用時機

當您需要以下操作時，請參考此技能：

• 使用 Prisma Client 撰寫資料庫查詢
• 執行 CRUD 操作（新增、讀取、更新、刪除）
• 篩選與排序資料
• 處理關聯
• 使用交易
• 設定客戶端選項

規則分類（依優先順序）

優先順序	分類	影響	前綴
1	客戶端建構	高	constructor
2	模型查詢	關鍵	model-queries
3	查詢形狀	高	query-options
4	篩選	高	filters
5	關聯	高	relations
6	交易	關鍵	transactions
7	原始 SQL	關鍵	raw-queries
8	客戶端方法	中	client-methods

快速參考

• constructor - PrismaClient 設定、轉接器配置、日誌記錄及 SQL 註解外掛
• model-queries - CRUD 操作及批次操作
• query-options - select、include、omit、排序、分頁
• filters - 純量與邏輯篩選運算子
• relations - 關聯讀取與巢狀寫入
• transactions - 陣列與互動式交易模式
• raw-queries - $queryRaw 與 $executeRaw 安全性
• client-methods - 生命週期方法、擴充功能及 satisfies 模式（用於 prisma-client）

客戶端實例化

import { PrismaClient } from '../generated/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({
  connectionString: process.env.DATABASE_URL
})

const prisma = new PrismaClient({ adapter })

模型查詢方法

方法	說明
findUnique()	依唯一欄位查詢單筆記錄
findUniqueOrThrow()	查詢單筆，否則拋出錯誤
findFirst()	查詢第一筆符合條件的記錄
findFirstOrThrow()	查詢第一筆，否則拋出錯誤
findMany()	查詢多筆記錄
create()	新增一筆記錄
createMany()	新增多筆記錄
createManyAndReturn()	新增多筆記錄並回傳
update()	更新一筆記錄
updateMany()	更新多筆記錄
updateManyAndReturn()	更新多筆記錄並回傳
upsert()	更新或新增記錄
delete()	刪除一筆記錄
deleteMany()	刪除多筆記錄
count()	計算符合條件的記錄數
aggregate()	彙總值（總和、平均等）
groupBy()	分組並彙總

查詢選項

選項	說明
where	篩選條件
select	要包含的欄位
include	要載入的關聯
omit	要排除的欄位
orderBy	排序方式
take	限制結果數量
skip	跳過結果（分頁）
cursor	基於游標的分頁
distinct	僅回傳唯一值

客戶端方法

方法	說明
$connect()	明確連線至資料庫
$disconnect()	中斷資料庫連線
$transaction()	執行交易
$queryRaw()	執行原始 SQL 查詢
$executeRaw()	執行原始 SQL 指令
$on()	訂閱事件
$extends()	新增擴充功能

快速範例

查詢記錄

// 依唯一欄位查詢
const user = await prisma.user.findUnique({
  where: { email: 'alice@prisma.io' }
})

// 使用篩選條件查詢
const users = await prisma.user.findMany({
  where: { role: 'ADMIN' },
  orderBy: { createdAt: 'desc' },
  take: 10
})

新增記錄

const user = await prisma.user.create({
  data: {
    email: 'alice@prisma.io',
    name: 'Alice',
    posts: {
      create: { title: 'Hello World' }
    }
  },
  include: { posts: true }
})

更新記錄

const user = await prisma.user.update({
  where: { id: 1 },
  data: { name: 'Alice Smith' }
})

刪除記錄

await prisma.user.delete({
  where: { id: 1 }
})

交易

const [user, post] = await prisma.$transaction([
  prisma.user.create({ data: { email: 'alice@prisma.io' } }),
  prisma.post.create({ data: { title: 'Hello', authorId: 1 } })
])

規則檔案

詳細 API 文件：

references/constructor.md        - PrismaClient 建構選項
references/model-queries.md      - CRUD 操作
references/query-options.md      - select、include、omit、where、orderBy
references/filters.md            - 篩選條件與運算子
references/relations.md          - 關聯查詢與巢狀操作
references/transactions.md       - 交易 API
references/raw-queries.md        - $queryRaw、$executeRaw
references/client-methods.md     - $connect、$disconnect、$on、$extends

篩選運算子

運算子	說明
equals	完全相符
not	不等於
in	在陣列中
notIn	不在陣列中
lt、lte	小於
gt、gte	大於
contains	字串包含
startsWith	字串開頭為
endsWith	字串結尾為
mode	大小寫敏感度

關聯篩選

運算子	說明
some	至少一筆關聯記錄符合
every	所有關聯記錄符合
none	無關聯記錄符合
is	關聯記錄符合（一對一）
isNot	關聯記錄不符合

資源

• Prisma Client API 參考文件
• CRUD 操作
• 篩選與排序

使用方式

從上方表格中選取分類，然後開啟對應的參考檔案以取得實作細節與範例。