Package io.github.flink.gcp.connector.spanner.sink

Enum ConstraintViolationPolicy

java.lang.Object
java.lang.Enum<ConstraintViolationPolicy>
io.github.flink.gcp.connector.spanner.sink.ConstraintViolationPolicy
All Implemented Interfaces:
Serializable, Comparable<ConstraintViolationPolicy>, java.lang.constant.Constable
@Public public enum ConstraintViolationPolicy extends Enum<ConstraintViolationPolicy>
What the sink does with a mutation Spanner refuses for violating a constraint.

Which refusals those are, measured rather than assumed (2026-08-09, one run, emulator v1.5.56): a NULL in a NOT NULL column, a value past its column's length and a foreign-key violation come back as FAILED_PRECONDITION; a CHECK constraint comes back as OUT_OF_RANGE. This policy covers both statuses. A duplicate key or a unique-index collision is not among them — that is ALREADY_EXISTS, which is always routed.

This is a policy rather than a fixed rule because the two readings of such a refusal are both defensible and only the pipeline's owner knows which applies. A constraint violation usually says the mapping from records to columns is wrong — every record of that shape will be refused, so shedding them one at a time hides a systematic problem behind a green job. But a stream that genuinely carries occasional records the schema will not accept wants them captured and the job kept running, which is what a failure handler is for.

The default is FAIL_JOB because it is the conservative one: it cannot lose a record, and it makes the problem visible immediately. There is a second reason to keep it the default. Spanner answers every write with FAILED_PRECONDITION while its CMEK key is disabled, destroyed or unreachable, and restores service by itself when the key comes back — so a job that routed this status into a dropping handler would shed its whole stream during a key incident rather than waiting it out.

See Also:

  • Enum Constant Details

    • FAIL_JOB

      public static final ConstraintViolationPolicy FAIL_JOB
      Fail the job. The record is not lost — it is replayed from the source on restart — but a stream that keeps producing such records will not make progress until the constraint or the mapping is fixed.

    • ROUTE_TO_FAILURE_HANDLER

      public static final ConstraintViolationPolicy ROUTE_TO_FAILURE_HANDLER
      Hand the mutation to the configured failedMutationHandler, like any other per-record refusal. What happens then is that handler's decision: FailureHandler.failJob() still fails the job, logAndDrop() drops the record, and sendToDeadLetterQueue(...) captures it. Choosing this and a dropping handler is a decision to lose records the schema refuses, which is exactly what makes it worth stating in the job rather than assuming.

  • Method Details

    • values

      public static ConstraintViolationPolicy[] values()
      Returns an array containing the constants of this enum type, in the order they are declared.
      Returns:
      an array containing the constants of this enum type, in the order they are declared

    • valueOf

      public static ConstraintViolationPolicy valueOf(String name)
      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum type has no constant with the specified name
      NullPointerException - if the argument is null