Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minor: improve TableReference docs #9952

Merged
merged 3 commits into from
Apr 5, 2024
Merged

Minor: improve TableReference docs #9952

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0efbcd0
Minor: improve TableReference docs
alamb Apr 4, 2024
a1d5965
Clarify normalization
alamb Apr 5, 2024
676a17c
Merge remote-tracking branch 'apache/main' into alamb/owned_docs
alamb Apr 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 22 additions & 17 deletions datafusion/common/src/table_reference.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
use crate::utils::{parse_identifiers_normalized, quote_identifier};
use std::sync::Arc;

/// A resolved path to a table of the form "catalog.schema.table"
/// A fully resolved path to a table of the form "catalog.schema.table"
#[derive(Debug, Clone)]
pub struct ResolvedTableReference {
/// The catalog (aka database) containing the table
Expand All @@ -35,17 +35,20 @@ impl std::fmt::Display for ResolvedTableReference {
}
}

/// [`TableReference`]s represent a multi part identifier (path) to a
/// table that may require further resolution.
/// A multi part identifier (path) to a table that may require further
/// resolution (e.g. `foo.bar`).
///
/// # Creating [`TableReference`]
/// [`TableReference`]s are cheap to `clone()` as they are implemented with
/// `Arc`.
///
/// See [`ResolvedTableReference`] for a fully resolved table reference.
///
/// When converting strings to [`TableReference`]s, the string is
/// parsed as though it were a SQL identifier, normalizing (convert to
/// lowercase) any unquoted identifiers.
/// # Creating [`TableReference`]
///
/// See [`TableReference::bare`] to create references without applying
/// normalization semantics
/// When converting strings to [`TableReference`]s, the string is parsed as
/// though it were a SQL identifier, normalizing (convert to lowercase) any
/// unquoted identifiers. [`TableReference::bare`] creates references without
/// applying normalization semantics.
///
/// # Examples
/// ```
Expand Down Expand Up @@ -128,7 +131,7 @@ impl TableReference {

/// Convenience method for creating a [`TableReference::Bare`]
///
/// As described on [`TableReference`] this does *NO* parsing at
/// As described on [`TableReference`] this does *NO* normalization at
/// all, so "Foo.Bar" stays as a reference to the table named
/// "Foo.Bar" (rather than "foo"."bar")
pub fn bare(table: impl Into<Arc<str>>) -> TableReference {
Expand All @@ -139,7 +142,7 @@ impl TableReference {

/// Convenience method for creating a [`TableReference::Partial`].
///
/// As described on [`TableReference`] this does *NO* parsing at all.
/// As described on [`TableReference`] this does *NO* normalization at all.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: technically the doc on TableReference doesn't make reference to partial or full functions as it only refers to bare

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is a good call -- I have clarified in a1d5965. Thank you @Jefffrey

pub fn partial(
schema: impl Into<Arc<str>>,
table: impl Into<Arc<str>>,
Expand All @@ -152,7 +155,7 @@ impl TableReference {

/// Convenience method for creating a [`TableReference::Full`]
///
/// As described on [`TableReference`] this does *NO* parsing at all.
/// As described on [`TableReference`] this does *NO* normalization at all.
pub fn full(
catalog: impl Into<Arc<str>>,
schema: impl Into<Arc<str>>,
Expand All @@ -165,7 +168,7 @@ impl TableReference {
}
}

/// Retrieve the actual table name, regardless of qualification
/// Retrieve the table name, regardless of qualification.
pub fn table(&self) -> &str {
match self {
Self::Full { table, .. }
Expand All @@ -174,15 +177,16 @@ impl TableReference {
}
}

/// Retrieve the schema name if in the `Partial` or `Full` qualification
/// Retrieve the schema name if [`Self::Partial]` or [`Self::`Full`],
/// `None` otherwise.
pub fn schema(&self) -> Option<&str> {
match self {
Self::Full { schema, .. } | Self::Partial { schema, .. } => Some(schema),
_ => None,
}
}

/// Retrieve the catalog name if in the `Full` qualification
/// Retrieve the catalog name if [`Self::Full`], `None` otherwise.
pub fn catalog(&self) -> Option<&str> {
match self {
Self::Full { catalog, .. } => Some(catalog),
Expand All @@ -191,7 +195,7 @@ impl TableReference {
}

/// Compare with another [`TableReference`] as if both are resolved.
/// This allows comparing across variants, where if a field is not present
/// This allows comparing across variants. If a field is not present
/// in both variants being compared then it is ignored in the comparison.
///
/// e.g. this allows a [`TableReference::Bare`] to be considered equal to a
Expand All @@ -215,7 +219,8 @@ impl TableReference {
}
}

/// Given a default catalog and schema, ensure this table reference is fully resolved
/// Given a default catalog and schema, ensure this table reference is fully
/// resolved
pub fn resolve(
self,
default_catalog: &str,
Expand Down
Loading