mz_persist_types/
txn.rs

1// Copyright Materialize, Inc. and contributors. All rights reserved.
2//
3// Use of this software is governed by the Business Source License
4// included in the LICENSE file.
5//
6// As of the Change Date specified in that file, in accordance with
7// the Business Source License, use of this software will be governed
8// by the Apache License, Version 2.0.
9
10//! Types for the txn-wal crate.
11
12use std::fmt::Debug;
13
14use serde::{Deserialize, Serialize};
15
16use crate::stats::PartStats;
17use crate::{Codec, Codec64, ShardId};
18
19/// The in-mem representation of an update in the txns shard.
20/// The ord implementation is not guaranteed to be meaningful; it's there for consolidation
21/// purposes only.
22#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, Ord, PartialOrd)]
23pub enum TxnsEntry {
24    /// A data shard register operation.
25    ///
26    /// The `[u8; 8]` is a Codec64 encoded timestamp.
27    Register(ShardId, [u8; 8]),
28    /// A batch written to a data shard in a txn.
29    ///
30    /// The `[u8; 8]` is a Codec64 encoded timestamp.
31    Append(ShardId, [u8; 8], Vec<u8>),
32}
33
34impl TxnsEntry {
35    /// Returns the ShardId of the data shard targeted by this entry.
36    pub fn data_id(&self) -> &ShardId {
37        match self {
38            TxnsEntry::Register(data_id, _) => data_id,
39            TxnsEntry::Append(data_id, _, _) => data_id,
40        }
41    }
42
43    /// Returns the decoded timestamp of this entry.
44    pub fn ts<T: Codec64>(&self) -> T {
45        match self {
46            TxnsEntry::Register(_, ts) => T::decode(*ts),
47            TxnsEntry::Append(_, ts, _) => T::decode(*ts),
48        }
49    }
50}
51
52/// An abstraction over the encoding format of [TxnsEntry].
53///
54/// This enables users of this crate to control how data is written to the txns
55/// shard (which will allow mz to present it as a normal introspection source).
56pub trait TxnsCodec: Debug {
57    /// The `K` type used in the txns shard.
58    type Key: Debug + Codec;
59    /// The `V` type used in the txns shard.
60    type Val: Debug + Codec;
61
62    /// Returns the Schemas to use with [Self::Key] and [Self::Val].
63    fn schemas() -> (<Self::Key as Codec>::Schema, <Self::Val as Codec>::Schema);
64    /// Encodes a [TxnsEntry] in the format persisted in the txns shard.
65    fn encode(e: TxnsEntry) -> (Self::Key, Self::Val);
66    /// Decodes a [TxnsEntry] from the format persisted in the txns shard.
67    ///
68    /// Implementations should panic if the values are invalid.
69    fn decode(key: Self::Key, val: Self::Val) -> TxnsEntry;
70
71    /// Returns if a part might include the given data shard based on pushdown
72    /// stats.
73    ///
74    /// False positives are okay (needless fetches) but false negatives are not
75    /// (incorrectness). Returns an Option to make `?` convenient, `None` is
76    /// treated the same as `Some(true)`.
77    fn should_fetch_part(data_id: &ShardId, stats: &PartStats) -> Option<bool>;
78}