Merge

file format 6
Rust SDK 1.0 preview

Combining packs into one. Inputs are verified first, records are matched by dedup key, and a strategy settles conflicts between entities.

The output always holds exactly one payload record that none of the inputs had; the other record rules are in Merge packs: the record rules.

On this page, Result<T> is std::result::Result<T, plxi_sdk::Error>.

Every public struct and enum with a public field or variant is marked #[non_exhaustive]: code outside the crate builds one through its constructors and matches an enum with a _ arm.

Functions

merge

Spec §8.1

pub fn merge(inputs: &[&[u8]], opts: &MergeOptions) -> Result<(Vec<u8>, MergeReport)>

Summary

Merge packs held in memory (spec §8.1): returns the merged pack's bytes and the report together, so the report is never separated from its output.

Preconditions, checked here before the records are merged: every input passes verify steps 1-8 (spec §8.1 precondition 1), and every appendix has container version byte 5, read from the bytes (appendix_legacy_version, precondition 2).

The output always holds exactly one payload record, written by merge; the payload records of the inputs are dropped. Merging a single pack therefore adds one record.

Parameters

inputs: &[&[u8]]
opts: &MergeOptions

Returns

Result<(Vec<u8>, MergeReport)>

Errors

The verify kind of a failing input; appendix_legacy_version; merge_conflict (no inputs, a tensor catalog section, an unregistered section type); appendix kinds from lifting sections.

Example

Example 5: Merge

Spec

Spec §8.1

Structs

struct

MergeOptions

Spec §8.1

#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct MergeOptions {
    pub strategy: MergeStrategy,
}

Summary: Merge options.
Fields: strategy: MergeStrategyConflict strategy (default: HigherSalience).
Example: Example 5: Merge
Spec: Spec §8.1

method

MergeOptions::with_strategy

Spec §8.1

pub fn with_strategy(strategy: MergeStrategy) -> MergeOptions

Summary: Options with strategy.
Parameters: strategy: MergeStrategy
Returns: MergeOptions
Example: Example 5: Merge
Spec: Spec §8.1

struct

MergeReport

Spec §8.1

#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct MergeReport {
    pub records_inserted: u64,
    pub records_updated: u64,
    pub records_skipped: u64,
    pub stubs_resolved: u64,
    pub conflicts: u64,
    pub sections_merged: u64,
    pub sections_deduped: u64,
}

Summary: What a merge did. The counts do not include the payload record that merge writes.
Fields: records_inserted: u64Records with a new dedup key.
records_updated: u64Records replaced by the incoming one.
records_skipped: u64Incoming records not taken (identical, or the existing one kept).
stubs_resolved: u64Stub entities replaced by full ones.
conflicts: u64Entity conflicts the strategy resolved.
sections_merged: u64Appendix sections in the output.
sections_deduped: u64Exact-duplicate appendix sections removed.
Example: Example 5: Merge
Spec: Spec §8.1

method

MergeReport::to_json_value

Spec §8.1

pub fn to_json_value(&self) -> Value

Summary: The report as JSON with snake_case keys.
Parameters: None.
Returns: Value
Example: Example 5: Merge
Spec: Spec §8.1

method

MergeReport::to_json

Spec §8.1

pub fn to_json(&self) -> String

Summary: to_json_value as compact JSON text.
Parameters: None.
Returns: String
Example: Example 5: Merge
Spec: Spec §8.1

Enums

enum

MergeStrategy

Spec §8.1

#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum MergeStrategy {
    #[default] HigherSalience,
    Latest,
    Union,
    Manual,
}

Summary: How entity conflicts resolve (spec §8.1 record rule 4).
Variants: HigherSalienceTake the incoming entity only if its salience is strictly greater.
LatestTake the incoming record.
UnionKeep the existing record.
ManualKeep the existing record and record the conflict as deferred.
Example: Example 5: Merge
Spec: Spec §8.1

method

MergeStrategy::as_str

Spec §8.1

pub fn as_str(self) -> &'static str

Summary: The strategy's snake_case name (higher_salience, latest, union, manual).
Parameters: None.
Returns: &'static str
Example: Example 5: Merge
Spec: Spec §8.1

method

MergeStrategy::from_name

Spec §8.1

pub fn from_name(name: &str) -> Option<MergeStrategy>

Summary: The strategy named name; None for an unknown name (a caller mistake, not an error kind).
Parameters: name: &str
Returns: Option<MergeStrategy>
Example: Example 5: Merge
Spec: Spec §8.1

Anyone may implement this format. Copying or republishing the text of this specification requires permission from Cintile Inc.