如何在Prisma Client中通过深度查询检索指定franchiseId和documentNumber的用户？

问题背景 #

使用Node.js + Prisma Client，现有模型定义如下：

model Client {
  id          Int            @id @default(autoincrement())
  createdAt   DateTime       @default(now())
  email       String         @unique
  name        String?
  lastName    String?
  password    String?
  profile     ClientProfile?
  franchise   Franchise      @relation(fields: [franchiseId], references: [id])
  franchiseId Int
  Records     Record[]
}

model ClientProfile {
  id                      Int       @id @default(autoincrement())
  createdAt               DateTime  @default(now())
  photo                   String?
  age                     DateTime?
  sex                     String?
  birthDate               DateTime?
  phone                   String?
  alternativePhone        String?
  documentType            String?
  documentNumber          String?
  taxIdentificationNumber String?
  frontPhotoID            String?
  IdPhotoBack             String?
  nationality             String?
  province                String?
  city                    String?
  note                    String?
  country                 String?
  address                 String?
  clientId                Int?      @unique
  client                  Client?   @relation(fields: [clientId], references: [id])
}

需求是检索拥有特定franchiseId和特定documentNumber的用户，尝试的查询代码如下：

const client = await this.prisma.userClient.findUnique({
  where: {
    franchiseId: 1,
    clientProfile: {
      documentNumber: "23212123221"
    }
  }
});

问题分析与解决方案 #

• 字段名称错误：Client模型中关联ClientProfile的字段是profile，不是clientProfile，这是核心语法错误。
• findUnique的限制：findUnique要求查询条件必须匹配模型的唯一约束（比如@id、@unique字段或复合唯一索引），而franchiseId + documentNumber并非预设的唯一约束，因此应该使用findFirst（返回匹配的第一个结果）或findMany（返回所有匹配结果）。

正确查询代码 #

获取单个匹配用户（findFirst）

const client = await this.prisma.client.findFirst({
  where: {
    franchiseId: 1,
    profile: {
      documentNumber: "23212123221"
    }
  },
  // 可选：如果需要返回关联的ClientProfile完整数据，添加include
  include: {
    profile: true
  }
});

获取所有匹配用户（findMany）

const clients = await this.prisma.client.findMany({
  where: {
    franchiseId: 1,
    profile: {
      documentNumber: "23212123221"
    }
  },
  include: {
    profile: true
  }
});

补充说明 #

如果需要确保franchiseId和documentNumber的组合唯一，可以在Prisma模型中添加复合唯一索引：

model Client {
  // 保留原有字段...
  franchiseId Int
  profile     ClientProfile?

  @@unique([franchiseId, profile.documentNumber])
}

添加索引后即可使用findUnique进行查询，但需注意此时profile必须存在（即documentNumber不能为null）。

内容的提问来源于stack exchange，提问作者Jcastillovnz