This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-datafusion.git
The following commit(s) were added to refs/heads/master by this push:
new ebb28f540 MINOR: improve docstrings on SessionContext (#3603)
ebb28f540 is described below
commit ebb28f54049813f1990a44ca75a8867175633180
Author: Andrew Lamb <[email protected]>
AuthorDate: Sun Sep 25 07:51:15 2022 -0400
MINOR: improve docstrings on SessionContext (#3603)
---
datafusion/core/src/execution/context.rs | 77 ++++++++++++----------
.../core/src/physical_plan/aggregates/mod.rs | 4 +-
2 files changed, 46 insertions(+), 35 deletions(-)
diff --git a/datafusion/core/src/execution/context.rs
b/datafusion/core/src/execution/context.rs
index bf80a23ab..f65c849e4 100644
--- a/datafusion/core/src/execution/context.rs
+++ b/datafusion/core/src/execution/context.rs
@@ -231,7 +231,7 @@ impl SessionContext {
self.table_factories.insert(file_type.to_string(), factory);
}
- /// Registers the RecordBatch as the specified table name
+ /// Registers the [`RecordBatch`] as the specified table name
pub fn register_batch(
&self,
table_name: &str,
@@ -256,7 +256,7 @@ impl SessionContext {
self.state.read().config.clone()
}
- /// Creates a dataframe that will execute a SQL query.
+ /// Creates a [`DataFrame`] that will execute a SQL query.
///
/// This method is `async` because queries of type `CREATE EXTERNAL TABLE`
/// might require the schema to be inferred.
@@ -604,7 +604,7 @@ impl SessionContext {
.insert(f.name.clone(), Arc::new(f));
}
- /// Creates a DataFrame for reading an Avro data source.
+ /// Creates a [`DataFrame`] for reading an Avro data source.
pub async fn read_avro(
&self,
table_path: impl AsRef<str>,
@@ -631,7 +631,7 @@ impl SessionContext {
self.read_table(Arc::new(provider))
}
- /// Creates a DataFrame for reading an Json data source.
+ /// Creates a [`DataFrame`] for reading an Json data source.
pub async fn read_json(
&mut self,
table_path: impl AsRef<str>,
@@ -666,7 +666,7 @@ impl SessionContext {
)))
}
- /// Creates a DataFrame for reading a CSV data source.
+ /// Creates a [`DataFrame`] for reading a CSV data source.
pub async fn read_csv(
&self,
table_path: impl AsRef<str>,
@@ -691,7 +691,7 @@ impl SessionContext {
self.read_table(Arc::new(provider))
}
- /// Creates a DataFrame for reading a Parquet data source.
+ /// Creates a [`DataFrame`] for reading a Parquet data source.
pub async fn read_parquet(
&self,
table_path: impl AsRef<str>,
@@ -715,7 +715,7 @@ impl SessionContext {
self.read_table(Arc::new(provider))
}
- /// Creates a DataFrame for reading a custom TableProvider.
+ /// Creates a [`DataFrame`] for reading a custom [`TableProvider`].
pub fn read_table(&self, provider: Arc<dyn TableProvider>) ->
Result<Arc<DataFrame>> {
Ok(Arc::new(DataFrame::new(
self.state.clone(),
@@ -724,7 +724,7 @@ impl SessionContext {
)))
}
- /// Creates a DataFrame for reading a custom RecordBatch
+ /// Creates a [`DataFrame`] for reading a [`RecordBatch`]
pub fn read_batch(&self, batch: RecordBatch) -> Result<Arc<DataFrame>> {
let provider = MemTable::try_new(batch.schema(), vec![vec![batch]])?;
Ok(Arc::new(DataFrame::new(
@@ -738,9 +738,13 @@ impl SessionContext {
)))
}
- /// Registers a table that uses the listing feature of the object store to
- /// find the files to be processed
- /// This is async because it might need to resolve the schema.
+ /// Registers a [`ListingTable]` that can assemble multiple files
+ /// from locations in an [`ObjectStore`] instance into a single
+ /// table.
+ ///
+ /// This method is `async` because it might need to resolve the schema.
+ ///
+ /// [`ObjectStore`]: object_store::ObjectStore
pub async fn register_listing_table(
&self,
name: &str,
@@ -762,8 +766,8 @@ impl SessionContext {
Ok(())
}
- /// Registers a CSV data source so that it can be referenced from SQL
statements
- /// executed against this context.
+ /// Registers a CSV file as a table which can referenced from SQL
+ /// statements executed against this context.
pub async fn register_csv(
&self,
name: &str,
@@ -785,8 +789,8 @@ impl SessionContext {
Ok(())
}
- // Registers a Json data source so that it can be referenced from SQL
statements
- /// executed against this context.
+ /// Registers a Json file as a table that it can be referenced
+ /// from SQL statements executed against this context.
pub async fn register_json(
&self,
name: &str,
@@ -807,8 +811,8 @@ impl SessionContext {
Ok(())
}
- /// Registers a Parquet data source so that it can be referenced from SQL
statements
- /// executed against this context.
+ /// Registers a Parquet file as a table that can be referenced from SQL
+ /// statements executed against this context.
pub async fn register_parquet(
&self,
name: &str,
@@ -828,8 +832,8 @@ impl SessionContext {
Ok(())
}
- /// Registers an Avro data source so that it can be referenced from SQL
statements
- /// executed against this context.
+ /// Registers an Avro file as a table that can be referenced from
+ /// SQL statements executed against this context.
pub async fn register_avro(
&self,
name: &str,
@@ -854,7 +858,7 @@ impl SessionContext {
/// it can be referenced from SQL statements executed against this
/// context.
///
- /// Returns the `CatalogProvider` previously registered for this
+ /// Returns the [`CatalogProvider`] previously registered for this
/// name, if any
pub fn register_catalog(
&self,
@@ -877,16 +881,15 @@ impl SessionContext {
state.catalog_list.register_catalog(name, catalog)
}
- /// Retrieves a `CatalogProvider` instance by name
+ /// Retrieves a [`CatalogProvider`] instance by name
pub fn catalog(&self, name: &str) -> Option<Arc<dyn CatalogProvider>> {
self.state.read().catalog_list.catalog(name)
}
- /// Registers a table using a custom `TableProvider` so that
- /// it can be referenced from SQL statements executed against this
- /// context.
+ /// Registers a [`TableProvider`] as a table that can be
+ /// referenced from SQL statements executed against this context.
///
- /// Returns the `TableProvider` previously registered for this
+ /// Returns the [`TableProvider`] previously registered for this
/// reference, if any
pub fn register_table<'a>(
&'a self,
@@ -914,8 +917,7 @@ impl SessionContext {
.deregister_table(table_ref.table())
}
- /// Check whether the given table exists in the schema provider or not
- /// Returns true if the table exists.
+ /// Return true if the specified table exists in the schema provider.
pub fn table_exist<'a>(
&'a self,
table_ref: impl Into<TableReference<'a>>,
@@ -928,10 +930,13 @@ impl SessionContext {
.table_exist(table_ref.table()))
}
- /// Retrieves a DataFrame representing a table previously registered by
calling the
- /// register_table function.
+ /// Retrieves a [`DataFrame`] representing a table previously
+ /// registered by calling the [`register_table`] function.
///
- /// Returns an error if no table has been registered with the provided
reference.
+ /// Returns an error if no table has been registered with the
+ /// provided reference.
+ ///
+ /// [`register_table`]: SessionContext::register_table
pub fn table<'a>(
&self,
table_ref: impl Into<TableReference<'a>>,
@@ -955,7 +960,8 @@ impl SessionContext {
}
}
- /// Returns the set of available tables in the default catalog and schema.
+ /// Returns the set of available tables in the default catalog and
+ /// schema.
///
/// Use [`table`] to get a specific table.
///
@@ -1286,8 +1292,13 @@ impl SessionConfig {
.unwrap()
}
- /// Convert configuration options to name-value pairs with values
converted to strings. Note
- /// that this method will eventually be deprecated and replaced by
[config_options].
+ /// Convert configuration options to name-value pairs with values
+ /// converted to strings.
+ ///
+ /// Note that this method will eventually be deprecated and
+ /// replaced by [`config_options`].
+ ///
+ /// [`config_options`]: SessionContext::config_option
pub fn to_props(&self) -> HashMap<String, String> {
let mut map = HashMap::new();
// copy configs from config_options
diff --git a/datafusion/core/src/physical_plan/aggregates/mod.rs
b/datafusion/core/src/physical_plan/aggregates/mod.rs
index 88eda63ed..aaf03b5c2 100644
--- a/datafusion/core/src/physical_plan/aggregates/mod.rs
+++ b/datafusion/core/src/physical_plan/aggregates/mod.rs
@@ -90,8 +90,8 @@ pub struct PhysicalGroupBy {
null_expr: Vec<(Arc<dyn PhysicalExpr>, String)>,
/// Null mask for each group in this grouping set. Each group is
/// composed of either one of the group expressions in expr or a null
- /// expression in null_expr. If groups[i][j] is true, then the the
- /// j-th expression in the i-th group is NULL, otherwise it is expr[j].
+ /// expression in null_expr. If `groups[i][j]` is true, then the the
+ /// j-th expression in the i-th group is NULL, otherwise it is `expr[j]`.
groups: Vec<Vec<bool>>,
}
