|
| 1 | +// Licensed to the Apache Software Foundation (ASF) under one |
| 2 | +// or more contributor license agreements. See the NOTICE file |
| 3 | +// distributed with this work for additional information |
| 4 | +// regarding copyright ownership. The ASF licenses this file |
| 5 | +// to you under the Apache License, Version 2.0 (the |
| 6 | +// "License"); you may not use this file except in compliance |
| 7 | +// with the License. You may obtain a copy of the License at |
| 8 | +// |
| 9 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | +// |
| 11 | +// Unless required by applicable law or agreed to in writing, |
| 12 | +// software distributed under the License is distributed on an |
| 13 | +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 14 | +// KIND, either express or implied. See the License for the |
| 15 | +// specific language governing permissions and limitations |
| 16 | +// under the License. |
| 17 | + |
| 18 | +//! Paimon system tables (`<table>$<name>`) as DataFusion table providers. |
| 19 | +//! |
| 20 | +//! Mirrors Java [SystemTableLoader](https://github.com/apache/paimon/blob/release-1.3/paimon-core/src/main/java/org/apache/paimon/table/system/SystemTableLoader.java): |
| 21 | +//! `TABLES` maps each system-table name to its builder function. |
| 22 | +
|
| 23 | +use std::sync::Arc; |
| 24 | + |
| 25 | +use datafusion::datasource::TableProvider; |
| 26 | +use datafusion::error::{DataFusionError, Result as DFResult}; |
| 27 | +use paimon::catalog::{Catalog, Identifier, SYSTEM_BRANCH_PREFIX, SYSTEM_TABLE_SPLITTER}; |
| 28 | +use paimon::table::Table; |
| 29 | + |
| 30 | +use crate::error::to_datafusion_error; |
| 31 | + |
| 32 | +mod options; |
| 33 | + |
| 34 | +type Builder = fn(Table) -> DFResult<Arc<dyn TableProvider>>; |
| 35 | + |
| 36 | +const TABLES: &[(&str, Builder)] = &[("options", options::build)]; |
| 37 | + |
| 38 | +/// Parse a Paimon object name into `(base_table, optional system_table_name)`. |
| 39 | +/// |
| 40 | +/// Mirrors Java [Identifier.splitObjectName](https://github.com/apache/paimon/blob/release-1.3/paimon-api/src/main/java/org/apache/paimon/catalog/Identifier.java). |
| 41 | +/// |
| 42 | +/// - `t` → `("t", None)` |
| 43 | +/// - `t$options` → `("t", Some("options"))` |
| 44 | +/// - `t$branch_main` → `("t", None)` (branch reference, not a system table) |
| 45 | +/// - `t$branch_main$options` → `("t", Some("options"))` (branch + system table) |
| 46 | +pub(crate) fn split_object_name(name: &str) -> (&str, Option<&str>) { |
| 47 | + let mut parts = name.splitn(3, SYSTEM_TABLE_SPLITTER); |
| 48 | + let base = parts.next().unwrap_or(name); |
| 49 | + match (parts.next(), parts.next()) { |
| 50 | + (None, _) => (base, None), |
| 51 | + (Some(second), None) => { |
| 52 | + if second.starts_with(SYSTEM_BRANCH_PREFIX) { |
| 53 | + (base, None) |
| 54 | + } else { |
| 55 | + (base, Some(second)) |
| 56 | + } |
| 57 | + } |
| 58 | + (Some(second), Some(third)) => { |
| 59 | + if second.starts_with(SYSTEM_BRANCH_PREFIX) { |
| 60 | + (base, Some(third)) |
| 61 | + } else { |
| 62 | + // `$` is legal in table names, so `t$foo$bar` falls through as |
| 63 | + // plain `t` and errors later as "table not found". |
| 64 | + (base, None) |
| 65 | + } |
| 66 | + } |
| 67 | + } |
| 68 | +} |
| 69 | + |
| 70 | +/// Returns true if `name` is a recognised Paimon system table suffix. |
| 71 | +pub(crate) fn is_registered(name: &str) -> bool { |
| 72 | + TABLES.iter().any(|(n, _)| name.eq_ignore_ascii_case(n)) |
| 73 | +} |
| 74 | + |
| 75 | +/// Wraps an already-loaded base table as the system table `name`. |
| 76 | +fn wrap_to_system_table(name: &str, base_table: Table) -> Option<DFResult<Arc<dyn TableProvider>>> { |
| 77 | + TABLES |
| 78 | + .iter() |
| 79 | + .find(|(n, _)| name.eq_ignore_ascii_case(n)) |
| 80 | + .map(|(_, build)| build(base_table)) |
| 81 | +} |
| 82 | + |
| 83 | +/// Loads `<base>$<system_name>` from the catalog and wraps it as a system |
| 84 | +/// table provider. |
| 85 | +/// |
| 86 | +/// - Unknown `system_name` → `Ok(None)` (DataFusion reports "table not found") |
| 87 | +/// - Base table missing → `Err(Plan)` so users can distinguish it from an |
| 88 | +/// unknown system name |
| 89 | +pub(crate) async fn load( |
| 90 | + catalog: Arc<dyn Catalog>, |
| 91 | + database: String, |
| 92 | + base: String, |
| 93 | + system_name: String, |
| 94 | +) -> DFResult<Option<Arc<dyn TableProvider>>> { |
| 95 | + if !is_registered(&system_name) { |
| 96 | + return Ok(None); |
| 97 | + } |
| 98 | + let identifier = Identifier::new(database, base.clone()); |
| 99 | + match catalog.get_table(&identifier).await { |
| 100 | + Ok(table) => wrap_to_system_table(&system_name, table) |
| 101 | + .expect("is_registered guarantees a builder") |
| 102 | + .map(Some), |
| 103 | + Err(paimon::Error::TableNotExist { .. }) => Err(DataFusionError::Plan(format!( |
| 104 | + "Cannot read system table `${system_name}`: \ |
| 105 | + base table `{base}` does not exist" |
| 106 | + ))), |
| 107 | + Err(e) => Err(to_datafusion_error(e)), |
| 108 | + } |
| 109 | +} |
| 110 | + |
| 111 | +#[cfg(test)] |
| 112 | +mod tests { |
| 113 | + use super::{is_registered, split_object_name}; |
| 114 | + |
| 115 | + #[test] |
| 116 | + fn is_registered_is_case_insensitive() { |
| 117 | + assert!(is_registered("options")); |
| 118 | + assert!(is_registered("Options")); |
| 119 | + assert!(is_registered("OPTIONS")); |
| 120 | + assert!(!is_registered("nonsense")); |
| 121 | + } |
| 122 | + |
| 123 | + #[test] |
| 124 | + fn plain_table_name() { |
| 125 | + assert_eq!(split_object_name("orders"), ("orders", None)); |
| 126 | + } |
| 127 | + |
| 128 | + #[test] |
| 129 | + fn system_table_only() { |
| 130 | + assert_eq!( |
| 131 | + split_object_name("orders$options"), |
| 132 | + ("orders", Some("options")) |
| 133 | + ); |
| 134 | + } |
| 135 | + |
| 136 | + #[test] |
| 137 | + fn branch_reference_is_not_a_system_table() { |
| 138 | + assert_eq!(split_object_name("orders$branch_main"), ("orders", None)); |
| 139 | + } |
| 140 | + |
| 141 | + #[test] |
| 142 | + fn branch_plus_system_table() { |
| 143 | + assert_eq!( |
| 144 | + split_object_name("orders$branch_main$options"), |
| 145 | + ("orders", Some("options")) |
| 146 | + ); |
| 147 | + } |
| 148 | + |
| 149 | + #[test] |
| 150 | + fn three_parts_without_branch_prefix_is_not_a_system_table() { |
| 151 | + assert_eq!(split_object_name("orders$foo$bar"), ("orders", None)); |
| 152 | + } |
| 153 | + |
| 154 | + #[test] |
| 155 | + fn system_table_name_preserves_case() { |
| 156 | + assert_eq!( |
| 157 | + split_object_name("orders$Options"), |
| 158 | + ("orders", Some("Options")) |
| 159 | + ); |
| 160 | + } |
| 161 | +} |
0 commit comments