Replace findOne with findUnique

[matthewmueller]

Problem

Today findOne depends on the unique constraints of the database to guarantee we'll find 0 or 1 records. According to the documentation:

The findOne query lets you retrieve a single database record by ID or another unique attribute. You can use the select and include options to determine which properties should be included on the returned object.

prisma.users.findOne({
  where: {
    email: "alice@prisma.io"
  }
})

Many people have been confused by this. They expect findOne to be more loose. More like: "Find the first record that matches my conditions."

Suggested solution

We're adding a new function called findFirst to solve for "Find the first record that matches my conditions." Here's the issue: #3676.

We're also considering to eventually replace findOne with findUnique. We feel this is a better name for what this method does.

In the short-term, we'd add findUnique as an alias to findOne and add a deprecation warning to findOne. In a later release, we'd remove findOne.

Alternatives

Leave it as is.

---

🙏 We're very curious to hear your thoughts! Do you see this as a problem like we do?

[beeman]

Personally I have a preference for findOne over findUnique as it's sorter and I think it works as expected. I feel that TypeScript helps you realize it only works with unique fields.

[matthewmueller]

Hey @beeman thanks for sharing your thoughts. I also really like short, concise names. Unfortunately, we've found that newcomers expect findOne to do what findFirst now does, so this adjustment could be a way to clear that confusion up.

[rinogo]

So, with these changes in place, for queries for unique rows, what's the difference between findFirst() and findUnique()?

I ask because if the DB is already enforcing uniqueness, won't the results of findFirst() and findUnique() be identical?

There appears to be a difference in the signature for the calls - findUnique() offers fewer parameter options. From what I see, findFirst() does everything that findUnique() does and more.

Ultimately, what I'm trying to understand is:

When I'm working with a table that already has my desired unique constraints in place, should I be using findUnique() or findFirst() and why? Or, perhaps it doesn't matter?

[malbaugh]

I would also like some clarification on the purpose/ ideal use case of findUnique vs findFirst. I can't find any commentary on why these two methods exist as findFirst seems to do everything findUnique does. Are there performance differences? I haven't been able to find any difference in my personal test cases.