diesel-rs/diesel

Documentation: Improve documentation for upsert `.filter_target()`

Open

#3791 opened on Sep 14, 2023

View on GitHub
 (3 comments) (0 reactions) (0 assignees)Rust (12,054 stars) (1,003 forks)batch import
documentationhelp wanted

Description

Setup

Versions

  • Rust: 1.70
  • Diesel: 2.1.0
  • Database: Postgres (cockroach)
  • Operating System: Mac OS 13

Feature Flags

  • diesel: ["chrono", "uuid", "serde_json"]

Problem Description

Unless I missed something, I was not able to find an example for using .filter_target() in the inline documentation. This corresponds to ON CONFLICT ... WHERE index_predicate DO UPDATE SET ..., which is different from the WHERE clause after DO UPDATE. It took me a bit of digging to figure out that diesel actually supports this.

It would be great if the we can add an example for this use case.

What are you trying to accomplish?

Using the ON CONFLICT ... WHERE index_predicate syntax with partial unique indexes.

What is the expected output?

N/A

What is the actual output?

N/A

Are you seeing any additional errors?

N/A

Steps to reproduce

Documentation for normal on conflict do update with extensive examples. https://docs.diesel.rs/2.1.x/diesel/upsert/struct.IncompleteOnConflict.html#examples

filter_target function is grouped with the trait https://docs.diesel.rs/2.1.x/diesel/upsert/struct.IncompleteOnConflict.html#method.filter_target

Checklist

  • (N/A, inline doc) This issue can be reproduced on Rust's stable channel. (Your issue will be closed if this is not the case)
  • (N/A, inline doc) This issue can be reproduced without requiring a third party crate

Potential solution

I propose that all the examples can be moved to the upsert module or the IncompleteOnConflict struct, which will make more sense if we were to add an example using filter_target()

PS: There should be a separate issue template documentation related issues.

Contributor guide

Tech stack
rustpostgresql
Domain
databasedocumentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
RustDiesel basicsSQL upsert syntax
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
Examine the documented examples for `IncompleteOnConflict` at https://docs.diesel.rs/2.1.x/diesel/upsert/struct.IncompleteOnConflict.html#examples. Look for the `filter target` method in the same struct. The issue suggests moving existing examples to the `upsert` module or the struct's docs and adding a new example demonstrating `ON CONFLICT ... WHERE index predicate` using `filter target()`. Refer to the linked docs and the issue's potential solution for guidance.