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}