From 50a9dd5d7a697a894f2b8028190b8d1cb31a1096 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 21 Jun 2022 11:04:39 -0400 Subject: [PATCH] minor: add a diagram to docstring for DictionaryArray (#1909) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * minor: add a diagram to docstring for DictionaryArray * minor: clarify docstring on `DictionaryArray::lookup_key` * Apply suggestions from code review Co-authored-by: Ruihang Xia Co-authored-by: Jörn Horstmann * make values smaller and keys larger Co-authored-by: Wakahisa Co-authored-by: Ruihang Xia Co-authored-by: Jörn Horstmann --- arrow/src/array/array_dictionary.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/arrow/src/array/array_dictionary.rs b/arrow/src/array/array_dictionary.rs index cff3daabb71d..d0222ba9d475 100644 --- a/arrow/src/array/array_dictionary.rs +++ b/arrow/src/array/array_dictionary.rs @@ -33,6 +33,34 @@ use crate::error::Result; /// This is mostly used to represent strings or a limited set of primitive types as integers, /// for example when doing NLP analysis or representing chromosomes by name. /// +/// [`DictionaryArray`] are represented using a `keys` array and a +/// `values` array, which may be different lengths. The `keys` array +/// stores indexes in the `values` array which holds +/// the corresponding logical value, as shown here: +/// +/// ```text +/// ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ +/// ┌─────────────────┐ ┌─────────┐ │ ┌─────────────────┐ +/// │ │ A │ │ 0 │ │ A │ values[keys[0]] +/// ├─────────────────┤ ├─────────┤ │ ├─────────────────┤ +/// │ │ D │ │ 2 │ │ B │ values[keys[1]] +/// ├─────────────────┤ ├─────────┤ │ ├─────────────────┤ +/// │ │ B │ │ 2 │ │ B │ values[keys[2]] +/// └─────────────────┘ ├─────────┤ │ ├─────────────────┤ +/// │ │ 1 │ │ D │ values[keys[3]] +/// ├─────────┤ │ ├─────────────────┤ +/// │ │ 1 │ │ D │ values[keys[4]] +/// ├─────────┤ │ ├─────────────────┤ +/// │ │ 0 │ │ A │ values[keys[5]] +/// └─────────┘ │ └─────────────────┘ +/// │ values keys +/// ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ +/// Logical array +/// Contents +/// DictionaryArray +/// length = 6 +/// ``` +/// /// Example **with nullable** data: /// /// ```