| |
| |
| <!DOCTYPE html> |
| |
| |
| <html lang="en" data-content_root="" > |
| |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> |
| |
| <title>Table — Apache Arrow v17.0.0.dev52</title> |
| |
| |
| |
| <script data-cfasync="false"> |
| document.documentElement.dataset.mode = localStorage.getItem("mode") || ""; |
| document.documentElement.dataset.theme = localStorage.getItem("theme") || "light"; |
| </script> |
| |
| <!-- Loaded before other Sphinx assets --> |
| <link href="../_static/styles/theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link href="../_static/styles/bootstrap.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link href="../_static/styles/pydata-sphinx-theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| |
| |
| <link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" /> |
| <link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" /> |
| |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/copybutton.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css" /> |
| |
| <!-- Pre-loaded scripts that we'll load fully later --> |
| <link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae" /> |
| <link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" /> |
| <script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script> |
| |
| <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> |
| <script src="../_static/doctools.js"></script> |
| <script src="../_static/sphinx_highlight.js"></script> |
| <script src="../_static/clipboard.min.js"></script> |
| <script src="../_static/copybutton.js"></script> |
| <script src="../_static/design-tabs.js"></script> |
| <script>DOCUMENTATION_OPTIONS.pagename = 'java/table';</script> |
| <script> |
| DOCUMENTATION_OPTIONS.theme_version = '0.15.2'; |
| DOCUMENTATION_OPTIONS.theme_switcher_json_url = '/docs/_static/versions.json'; |
| DOCUMENTATION_OPTIONS.theme_switcher_version_match = 'dev/'; |
| DOCUMENTATION_OPTIONS.show_version_warning_banner = true; |
| </script> |
| <link rel="canonical" href="https://arrow.apache.org/docs/java/table.html" /> |
| <link rel="icon" href="../_static/favicon.ico"/> |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="Reading/Writing IPC formats" href="ipc.html" /> |
| <link rel="prev" title="Tabular Data" href="vector_schema_root.html" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <meta name="docsearch:language" content="en"/> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ |
| /* We explicitly disable cookie tracking to avoid privacy issues */ |
| _paq.push(['disableCookies']); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="https://analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '20']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| |
| </head> |
| |
| |
| <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode=""> |
| |
| |
| |
| <a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a> |
| |
| <div id="pst-scroll-pixel-helper"></div> |
| |
| <button type="button" class="btn rounded-pill" id="pst-back-to-top"> |
| <i class="fa-solid fa-arrow-up"></i> |
| Back to top |
| </button> |
| |
| |
| <input type="checkbox" |
| class="sidebar-toggle" |
| name="__primary" |
| id="__primary"/> |
| <label class="overlay overlay-primary" for="__primary"></label> |
| |
| <input type="checkbox" |
| class="sidebar-toggle" |
| name="__secondary" |
| id="__secondary"/> |
| <label class="overlay overlay-secondary" for="__secondary"></label> |
| |
| <div class="search-button__wrapper"> |
| <div class="search-button__overlay"></div> |
| <div class="search-button__search-container"> |
| <form class="bd-search d-flex align-items-center" |
| action="../search.html" |
| method="get"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <input type="search" |
| class="form-control" |
| name="q" |
| id="search-input" |
| placeholder="Search the docs ..." |
| aria-label="Search the docs ..." |
| autocomplete="off" |
| autocorrect="off" |
| autocapitalize="off" |
| spellcheck="false"/> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span> |
| </form></div> |
| </div> |
| |
| <header class="bd-header navbar navbar-expand-lg bd-navbar"> |
| <div class="bd-header__inner bd-page-width"> |
| <label class="sidebar-toggle primary-toggle" for="__primary"> |
| <span class="fa-solid fa-bars"></span> |
| </label> |
| |
| |
| <div class="col-lg-3 navbar-header-items__start"> |
| |
| <div class="navbar-item"> |
| |
| |
| |
| <a class="navbar-brand logo" href="../index.html"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <img src="../_static/arrow.png" class="logo__image only-light" alt="Apache Arrow v17.0.0.dev52 - Home"/> |
| <script>document.write(`<img src="../_static/arrow-dark.png" class="logo__image only-dark" alt="Apache Arrow v17.0.0.dev52 - Home"/>`);</script> |
| |
| |
| </a></div> |
| |
| </div> |
| |
| <div class="col-lg-9 navbar-header-items"> |
| |
| <div class="me-auto navbar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav class="navbar-nav"> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../format/index.html"> |
| Specifications |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../developers/index.html"> |
| Development |
| </a> |
| </li> |
| |
| <li class="nav-item dropdown"> |
| <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links"> |
| Implementations |
| </button> |
| <ul id="pst-nav-more-links" class="dropdown-menu"> |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html"> |
| C/GLib |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../cpp/index.html"> |
| C++ |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md"> |
| C# |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17"> |
| Go |
| </a> |
| </li> |
| |
| |
| <li class="nav-item current active"> |
| <a class="nav-link dropdown-item nav-internal" href="index.html"> |
| Java |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../js/index.html"> |
| JavaScript |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/"> |
| Julia |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md"> |
| MATLAB |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/"> |
| nanoarrow |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../python/index.html"> |
| Python |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../r/index.html"> |
| R |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md"> |
| Ruby |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/"> |
| Rust |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../status.html"> |
| Implementation Status |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/"> |
| C++ cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/"> |
| Java cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/"> |
| Python cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/"> |
| R cookbook |
| </a> |
| </li> |
| |
| </ul> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| <div class="navbar-header-items__end"> |
| |
| <div class="navbar-item navbar-persistent--container"> |
| |
| |
| <script> |
| document.write(` |
| <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <span class="search-button__default-text">Search</span> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span> |
| </button> |
| `); |
| </script> |
| </div> |
| |
| |
| <div class="navbar-item"> |
| <script> |
| document.write(` |
| <div class="version-switcher__container dropdown"> |
| <button id="pst-version-switcher-button-2" |
| type="button" |
| class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" |
| data-bs-toggle="dropdown" |
| aria-haspopup="listbox" |
| aria-controls="pst-version-switcher-list-2" |
| aria-label="Version switcher list" |
| > |
| Choose version <!-- this text may get changed later by javascript --> |
| <span class="caret"></span> |
| </button> |
| <div id="pst-version-switcher-list-2" |
| class="version-switcher__menu dropdown-menu list-group-flush py-0" |
| role="listbox" aria-labelledby="pst-version-switcher-button-2"> |
| <!-- dropdown will be populated by javascript on page load --> |
| </div> |
| </div> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"> |
| |
| <script> |
| document.write(` |
| <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span> |
| </button> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links navbar-nav" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">X</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| |
| <div class="navbar-persistent--mobile"> |
| |
| <script> |
| document.write(` |
| <button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="fa-solid fa-magnifying-glass"></i> |
| <span class="search-button__default-text">Search</span> |
| <span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span> |
| </button> |
| `); |
| </script> |
| </div> |
| |
| |
| |
| <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0"> |
| <span class="fa-solid fa-outdent"></span> |
| </label> |
| |
| </div> |
| |
| </header> |
| |
| |
| <div class="bd-container"> |
| <div class="bd-container__inner bd-page-width"> |
| |
| |
| |
| <div class="bd-sidebar-primary bd-sidebar"> |
| |
| |
| |
| <div class="sidebar-header-items sidebar-primary__section"> |
| |
| |
| <div class="sidebar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav class="navbar-nav"> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../format/index.html"> |
| Specifications |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link nav-internal" href="../developers/index.html"> |
| Development |
| </a> |
| </li> |
| |
| <li class="nav-item dropdown"> |
| <button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links-2"> |
| Implementations |
| </button> |
| <ul id="pst-nav-more-links-2" class="dropdown-menu"> |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html"> |
| C/GLib |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../cpp/index.html"> |
| C++ |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md"> |
| C# |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17"> |
| Go |
| </a> |
| </li> |
| |
| |
| <li class="nav-item current active"> |
| <a class="nav-link dropdown-item nav-internal" href="index.html"> |
| Java |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../js/index.html"> |
| JavaScript |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/"> |
| Julia |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md"> |
| MATLAB |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/"> |
| nanoarrow |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../python/index.html"> |
| Python |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../r/index.html"> |
| R |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md"> |
| Ruby |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/"> |
| Rust |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-internal" href="../status.html"> |
| Implementation Status |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/"> |
| C++ cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/"> |
| Java cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/"> |
| Python cookbook |
| </a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/"> |
| R cookbook |
| </a> |
| </li> |
| |
| </ul> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| |
| <div class="sidebar-header-items__end"> |
| |
| <div class="navbar-item"> |
| <script> |
| document.write(` |
| <div class="version-switcher__container dropdown"> |
| <button id="pst-version-switcher-button-3" |
| type="button" |
| class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" |
| data-bs-toggle="dropdown" |
| aria-haspopup="listbox" |
| aria-controls="pst-version-switcher-list-3" |
| aria-label="Version switcher list" |
| > |
| Choose version <!-- this text may get changed later by javascript --> |
| <span class="caret"></span> |
| </button> |
| <div id="pst-version-switcher-list-3" |
| class="version-switcher__menu dropdown-menu list-group-flush py-0" |
| role="listbox" aria-labelledby="pst-version-switcher-button-3"> |
| <!-- dropdown will be populated by javascript on page load --> |
| </div> |
| </div> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"> |
| |
| <script> |
| document.write(` |
| <button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span> |
| <span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span> |
| </button> |
| `); |
| </script></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links navbar-nav" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span> |
| <span class="sr-only">X</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| <div class="sidebar-primary-items__start sidebar-primary__section"> |
| <div class="sidebar-primary-item"> |
| <nav class="bd-docs-nav bd-links" |
| aria-label="Section Navigation"> |
| <p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p> |
| <div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav"> |
| <li class="toctree-l1"><a class="reference internal" href="quickstartguide.html">Quick Start Guide</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="overview.html">High-Level Overview</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="install.html">Installing Java Modules</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="memory.html">Memory Management</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="vector.html">ValueVector</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="vector_schema_root.html">Tabular Data</a></li> |
| <li class="toctree-l1 current active"><a class="current reference internal" href="#">Table</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="ipc.html">Reading/Writing IPC formats</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="algorithm.html">Java Algorithms</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="flight.html">Arrow Flight RPC</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="flight_sql.html">Arrow Flight SQL</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="flight_sql_jdbc_driver.html">Arrow Flight SQL JDBC Driver</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="dataset.html">Dataset</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="substrait.html">Substrait</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="cdata.html">C Data Interface</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="jdbc.html">Arrow JDBC Adapter</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="reference/index.html">Reference (javadoc)</a></li> |
| <li class="toctree-l1"><a class="reference external" href="https://arrow.apache.org/cookbook/java/">Java cookbook</a></li> |
| </ul> |
| </div> |
| </nav></div> |
| </div> |
| |
| |
| <div class="sidebar-primary-items__end sidebar-primary__section"> |
| </div> |
| |
| <div id="rtd-footer-container"></div> |
| |
| |
| </div> |
| |
| <main id="main-content" class="bd-main"> |
| |
| |
| <div class="bd-content"> |
| <div class="bd-article-container"> |
| |
| <div class="bd-header-article"> |
| <div class="header-article-items header-article__inner"> |
| |
| <div class="header-article-items__start"> |
| |
| <div class="header-article-item"> |
| |
| |
| |
| <nav aria-label="Breadcrumb"> |
| <ul class="bd-breadcrumbs"> |
| |
| <li class="breadcrumb-item breadcrumb-home"> |
| <a href="../index.html" class="nav-link" aria-label="Home"> |
| <i class="fa-solid fa-home"></i> |
| </a> |
| </li> |
| |
| <li class="breadcrumb-item"><a href="index.html" class="nav-link">Java Implementation</a></li> |
| |
| <li class="breadcrumb-item active" aria-current="page">Table</li> |
| </ul> |
| </nav> |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| |
| |
| |
| <div id="searchbox"></div> |
| <article class="bd-article"> |
| |
| <section id="table"> |
| <h1>Table<a class="headerlink" href="#table" title="Permalink to this heading">#</a></h1> |
| <p><strong>NOTE</strong>: The Table API is experimental and subject to change. See the list of limitations below.</p> |
| <p><a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/table/Table.html">Table</a> is an immutable tabular data structure based on <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/FieldVector.html">FieldVector</a>. Like <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/VectorSchemaRoot.html">VectorSchemaRoot</a>, <code class="docutils literal notranslate"><span class="pre">Table</span></code> is a columnar data structure backed by Arrow arrays, or more specifically, by <code class="docutils literal notranslate"><span class="pre">FieldVector</span></code> objects. It differs from <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> mainly in that it is fully immutable and lacks support for batch operations. Anyone processing batches of tabular data in a pipeline should continue to use <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code>. Finally, the <code class="docutils literal notranslate"><span class="pre">Table</span></code> API is mainly row-oriented, so in some ways it’s more like the JDBC API than the <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> API, but you can still use <code class="docutils literal notranslate"><span class="pre">FieldReaders</span></code> to work with data in a columnar fashion.</p> |
| <section id="mutation-in-table-and-vectorschemaroot"> |
| <h2>Mutation in Table and VectorSchemaRoot<a class="headerlink" href="#mutation-in-table-and-vectorschemaroot" title="Permalink to this heading">#</a></h2> |
| <p><code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> provides a thin wrapper on the vectors that hold its data. Individual vectors can be retrieved from a vector schema root. These vectors have <em>setters</em> for modifying their elements, making <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> immutable only by convention. The protocol for mutating a vector is documented in the <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/ValueVector.html">ValueVector</a> interface:</p> |
| <ul class="simple"> |
| <li><p>values need to be written in order (e.g. index 0, 1, 2, 5)</p></li> |
| <li><p>null vectors start with all values as null before writing anything</p></li> |
| <li><p>for variable width types, the offset vector should be all zeros before writing</p></li> |
| <li><p>you must call setValueCount before a vector can be read</p></li> |
| <li><p>you should never write to a vector once it has been read.</p></li> |
| </ul> |
| <p>The rules aren’t enforced by the API so the programmer is responsible for ensuring that they are followed. Failure to do so could lead to runtime exceptions.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">Table</span></code>, on the other hand, is immutable. The underlying vectors are not exposed. When a table is created from existing vectors, their memory is transferred to new vectors, so subsequent changes to the original vectors can’t impact the new table’s values.</p> |
| </section> |
| <section id="features-and-limitations"> |
| <h2>Features and limitations<a class="headerlink" href="#features-and-limitations" title="Permalink to this heading">#</a></h2> |
| <p>A basic set of table functionality is currently available:</p> |
| <ul class="simple"> |
| <li><p>Create a table from vectors or <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code></p></li> |
| <li><p>Iterate tables by row, or set the current row index directly</p></li> |
| <li><p>Access vector values as primitives, objects, and/or nullable <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/holders/ValueHolder.html">ValueHolder</a> instances (depending on type)</p></li> |
| <li><p>Get a <code class="docutils literal notranslate"><span class="pre">FieldReader</span></code> for any vector</p></li> |
| <li><p>Add and remove vectors, creating new tables</p></li> |
| <li><p>Encode and decode a table’s vectors using dictionary encoding</p></li> |
| <li><p>Export table data for use by native code</p></li> |
| <li><p>Print representative data to TSV strings</p></li> |
| <li><p>Get a table’s schema</p></li> |
| <li><p>Slice tables</p></li> |
| <li><p>Convert table to <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code></p></li> |
| </ul> |
| <p>Limitations in the 11.0.0 release:</p> |
| <ul class="simple"> |
| <li><p>No support <code class="docutils literal notranslate"><span class="pre">ChunkedArray</span></code> or any form of row-group. Support for chunked arrays or row groups will be considered for a future release.</p></li> |
| <li><p>No support for the C-Stream API. Support for the streaming API is contingent on chunked array support</p></li> |
| <li><p>No support for creating tables directly from Java POJOs. All data held by a table must be imported via a <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code>, or from collections or arrays of vectors.</p></li> |
| </ul> |
| </section> |
| <section id="the-table-api"> |
| <h2>The Table API<a class="headerlink" href="#the-table-api" title="Permalink to this heading">#</a></h2> |
| <p>Like <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code>, a table contains a <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/types/pojo/Schema.html">Schema</a> and an ordered collection of <code class="docutils literal notranslate"><span class="pre">FieldVector</span></code> objects, but it is designed to be accessed via a row-oriented interface.</p> |
| <section id="creating-a-table-from-a-vectorschemaroot"> |
| <h3>Creating a Table from a VectorSchemaRoot<a class="headerlink" href="#creating-a-table-from-a-vectorschemaroot" title="Permalink to this heading">#</a></h3> |
| <p>Tables are created from a <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> as shown below. The memory buffers holding the data are transferred from the vector schema root to new vectors in the new table, clearing the source vectors in the process. This ensures that the data in your new table is never changed. Since the buffers are transferred rather than copied, this is a very low overhead operation.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">someVectorSchemaRoot</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>If you now update the vectors held by the <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> (using some version of <cite>ValueVector#setSafe()</cite>), it would reflect those changes, but the values in table <em>t</em> are unchanged.</p> |
| </section> |
| <section id="creating-a-table-from-fieldvectors"> |
| <h3>Creating a Table from FieldVectors<a class="headerlink" href="#creating-a-table-from-fieldvectors" title="Permalink to this heading">#</a></h3> |
| <p>Tables can be created from <code class="docutils literal notranslate"><span class="pre">FieldVectors</span></code> as shown below, using ‘var-arg’ array arguments:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">IntVector</span><span class="w"> </span><span class="n">myVector</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">createMyIntVector</span><span class="p">();</span> |
| <span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">VectorSchemaRoot</span><span class="p">(</span><span class="n">myVector</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>or by passing a collection:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">IntVector</span><span class="w"> </span><span class="n">myVector</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">createMyIntVector</span><span class="p">();</span> |
| <span class="n">List</span><span class="o"><</span><span class="n">FieldVector</span><span class="o">></span><span class="w"> </span><span class="n">fvList</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">List</span><span class="p">.</span><span class="na">of</span><span class="p">(</span><span class="n">myVector</span><span class="p">);</span> |
| <span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">VectorSchemaRoot</span><span class="p">(</span><span class="n">fvList</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>It is rarely a good idea to share vectors between multiple vector schema roots, and it would not be a good idea to share them between vector schema roots and tables. Creating a <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> from a list of vectors does not cause the reference counts for the vectors to be incremented. Unless you manage the counts manually, the code below would lead to more references than reference counts, and that could lead to trouble. There is an implicit assumption that the vectors were created for use by <em>one</em> <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> that this code violates.</p> |
| <p><em>Don’t do this:</em></p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">IntVector</span><span class="w"> </span><span class="n">myVector</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">createMyIntVector</span><span class="p">();</span><span class="w"> </span><span class="c1">// Reference count for myVector = 1</span> |
| <span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">VectorSchemaRoot</span><span class="p">(</span><span class="n">myVector</span><span class="p">);</span><span class="w"> </span><span class="c1">// Still one reference</span> |
| <span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">VectorSchemaRoot</span><span class="p">(</span><span class="n">myVector</span><span class="p">);</span> |
| <span class="c1">// Ref count is still one, but there are two VSRs with a reference to myVector</span> |
| <span class="n">vsr2</span><span class="p">.</span><span class="na">clear</span><span class="p">();</span><span class="w"> </span><span class="c1">// Reference count for myVector is 0.</span> |
| </pre></div> |
| </div> |
| <p>What is happening is that the reference counter works at a lower level than the <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> interface. A reference counter counts references to <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/memory/ArrowBuf.html">ArrowBuf</a> instances that control memory buffers. It doesn’t count references to the vectors that hold those ArrowBufs. In the example above, each <code class="docutils literal notranslate"><span class="pre">ArrowBuf</span></code> is held by one vector, so there is only one reference. This distinction is blurred when you call the <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code>’s clear() method, which frees the memory held by each of the vectors it references even though another instance references the same vectors.</p> |
| <p>When you create tables from vectors, it’s assumed that there are no external references to those vectors. To be certain, the buffers underlying these vectors are transferred to new vectors in the new table, and the original vectors are cleared.</p> |
| <p><em>Don’t do this either, but note the difference from above:</em></p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">IntVector</span><span class="w"> </span><span class="n">myVector</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">createMyIntVector</span><span class="p">();</span><span class="w"> </span><span class="c1">// Reference count for myVector = 1</span> |
| <span class="n">Table</span><span class="w"> </span><span class="n">t1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">myVector</span><span class="p">);</span> |
| <span class="c1">// myVector is cleared; Table t1 has a new hidden vector with the data from myVector</span> |
| <span class="n">Table</span><span class="w"> </span><span class="n">t2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">myVector</span><span class="p">);</span> |
| <span class="c1">// t2 has no rows because myVector was just cleared</span> |
| <span class="c1">// t1 continues to have the data from the original vector</span> |
| <span class="n">t2</span><span class="p">.</span><span class="na">clear</span><span class="p">();</span> |
| <span class="c1">// no change because t2 is already empty and t1 is independent</span> |
| </pre></div> |
| </div> |
| <p>With tables, memory is explicitly transferred on instantiation so the buffers held by a table are held by <em>only</em> that table.</p> |
| </section> |
| <section id="creating-tables-with-dictionary-encoded-vectors"> |
| <h3>Creating Tables with dictionary-encoded vectors<a class="headerlink" href="#creating-tables-with-dictionary-encoded-vectors" title="Permalink to this heading">#</a></h3> |
| <p>Another point of difference is that <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> is uninformed about any dictionary-encoding of its vectors, while tables hold an optional <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/dictionary/DictionaryProvider.html">DictionaryProvider</a> instance. If any vectors in the source data are encoded, a DictionaryProvider must be set to un-encode the values.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">myVsr</span><span class="p">();</span> |
| <span class="n">DictionaryProvider</span><span class="w"> </span><span class="n">provider</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">myProvider</span><span class="p">();</span> |
| <span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vsr</span><span class="p">,</span><span class="w"> </span><span class="n">provider</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>In <code class="docutils literal notranslate"><span class="pre">Table</span></code>, dictionaries are used like they are with vectors. To decode a vector, the user provides the name of the vector to decode and the dictionary id:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vsr</span><span class="p">,</span><span class="w"> </span><span class="n">provider</span><span class="p">);</span> |
| <span class="n">ValueVector</span><span class="w"> </span><span class="n">decodedName</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">decode</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span><span class="w"> </span><span class="mi">1L</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>To encode a vector from a table, a similar approach is used:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vsr</span><span class="p">,</span><span class="w"> </span><span class="n">provider</span><span class="p">);</span> |
| <span class="n">ValueVector</span><span class="w"> </span><span class="n">encodedName</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">encode</span><span class="p">(</span><span class="s">"name"</span><span class="p">,</span><span class="w"> </span><span class="mi">1L</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="freeing-memory-explicitly"> |
| <h3>Freeing memory explicitly<a class="headerlink" href="#freeing-memory-explicitly" title="Permalink to this heading">#</a></h3> |
| <p>Tables use off-heap memory that must be freed when it is no longer needed. <code class="docutils literal notranslate"><span class="pre">Table</span></code> implements <code class="docutils literal notranslate"><span class="pre">AutoCloseable</span></code> so the best way to create one is in a try-with-resources block:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">myMethodForGettingVsrs</span><span class="p">();</span> |
| <span class="w"> </span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vsr</span><span class="p">))</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="c1">// do useful things.</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>If you don’t use a try-with-resources block, you must close the table manually:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">vsr</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">myMethodForGettingVsrs</span><span class="p">();</span> |
| <span class="w"> </span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vsr</span><span class="p">);</span> |
| <span class="w"> </span><span class="c1">// do useful things.</span> |
| <span class="p">}</span><span class="w"> </span><span class="k">finally</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="n">vsr</span><span class="p">.</span><span class="na">close</span><span class="p">();</span> |
| <span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">close</span><span class="p">();</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>Manual closing should be performed in a finally block.</p> |
| </section> |
| <section id="getting-the-schema"> |
| <h3>Getting the schema<a class="headerlink" href="#getting-the-schema" title="Permalink to this heading">#</a></h3> |
| <p>You get the table’s schema just as you would with a vector schema root:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Schema</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">table</span><span class="p">.</span><span class="na">getSchema</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="adding-and-removing-vectors"> |
| <h3>Adding and removing vectors<a class="headerlink" href="#adding-and-removing-vectors" title="Permalink to this heading">#</a></h3> |
| <p><code class="docutils literal notranslate"><span class="pre">Table</span></code> provides facilities for adding and removing vectors modeled on the same functionality in <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code>. These operations return new instances rather than modifying the original instance in-place.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vectorList</span><span class="p">))</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="n">IntVector</span><span class="w"> </span><span class="n">v3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">IntVector</span><span class="p">(</span><span class="s">"3"</span><span class="p">,</span><span class="w"> </span><span class="n">intFieldType</span><span class="p">,</span><span class="w"> </span><span class="n">allocator</span><span class="p">);</span> |
| <span class="w"> </span><span class="n">Table</span><span class="w"> </span><span class="n">t2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">addVector</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">v3</span><span class="p">);</span> |
| <span class="w"> </span><span class="n">Table</span><span class="w"> </span><span class="n">t3</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">t2</span><span class="p">.</span><span class="na">removeVector</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span> |
| <span class="w"> </span><span class="c1">// don't forget to close t2 and t3</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="slicing-tables"> |
| <h3>Slicing tables<a class="headerlink" href="#slicing-tables" title="Permalink to this heading">#</a></h3> |
| <p><code class="docutils literal notranslate"><span class="pre">Table</span></code> supports <em>slice()</em> operations, where a slice of a source table is a second Table that refers to a single, contiguous range of rows in the source.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vectorList</span><span class="p">))</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="n">Table</span><span class="w"> </span><span class="n">t2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">slice</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span><span class="w"> </span><span class="mi">200</span><span class="p">);</span><span class="w"> </span><span class="c1">// creates a slice referencing the values in range (100, 200]</span> |
| <span class="w"> </span><span class="p">...</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>This raises the question: If you create a slice with <em>all</em> the values in the source table (as shown below), how would that differ from a new Table constructed with the same vectors as the source?</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="w"> </span><span class="p">(</span><span class="n">Table</span><span class="w"> </span><span class="n">t</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Table</span><span class="p">(</span><span class="n">vectorList</span><span class="p">))</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="n">Table</span><span class="w"> </span><span class="n">t2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">slice</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span><span class="w"> </span><span class="n">t</span><span class="p">.</span><span class="na">getRowCount</span><span class="p">());</span><span class="w"> </span><span class="c1">// creates a slice referencing all the values in t</span> |
| <span class="w"> </span><span class="c1">// ...</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>The difference is that when you <em>construct</em> a new table, the buffers are transferred from the source vectors to new vectors in the destination. With a slice, both tables share the same underlying vectors. That’s OK, though, since both tables are immutable.</p> |
| </section> |
| <section id="using-fieldreaders"> |
| <h3>Using FieldReaders<a class="headerlink" href="#using-fieldreaders" title="Permalink to this heading">#</a></h3> |
| <p>You can get a <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/complex/reader/FieldReader.html">FieldReader</a> for any vector in the Table passing either the <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/types/pojo/Field.html">Field</a>, vector index, or vector name as an argument. The signatures are the same as in <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code>.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">FieldReader</span><span class="w"> </span><span class="n">nameReader</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">table</span><span class="p">.</span><span class="na">getReader</span><span class="p">(</span><span class="s">"user_name"</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="row-operations"> |
| <h3>Row operations<a class="headerlink" href="#row-operations" title="Permalink to this heading">#</a></h3> |
| <p>Row-based access is supported by the <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/vector/table/Row.html">Row</a> object. <code class="docutils literal notranslate"><span class="pre">Row</span></code> provides <em>get()</em> methods by both vector name and vector position, but no <em>set()</em> operations.</p> |
| <p>It is important to recognize that rows are NOT reified as objects, but rather operate like a cursor where the data from numerous logical rows in the table can be viewed (one at a time) using the same <code class="docutils literal notranslate"><span class="pre">Row</span></code> instance. See “Moving from row-to-row” below for information about navigating through the table.</p> |
| </section> |
| <section id="getting-a-row"> |
| <h3>Getting a row<a class="headerlink" href="#getting-a-row" title="Permalink to this heading">#</a></h3> |
| <p>Calling <cite>immutableRow()</cite> on any table instance returns a new <code class="docutils literal notranslate"><span class="pre">Row</span></code> instance.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Row</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">table</span><span class="p">.</span><span class="na">immutableRow</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="moving-from-row-to-row"> |
| <h3>Moving from row-to-row<a class="headerlink" href="#moving-from-row-to-row" title="Permalink to this heading">#</a></h3> |
| <p>Since rows are iterable, you can traverse a table using a standard while loop:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Row</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">table</span><span class="p">.</span><span class="na">immutableRow</span><span class="p">();</span> |
| <span class="k">while</span><span class="w"> </span><span class="p">(</span><span class="n">r</span><span class="p">.</span><span class="na">hasNext</span><span class="p">())</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="na">next</span><span class="p">();</span> |
| <span class="w"> </span><span class="c1">// do something useful here</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p><code class="docutils literal notranslate"><span class="pre">Table</span></code> implements <cite>Iterable<Row></cite> so you can access rows directly from a table in an enhanced <em>for</em> loop:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="k">for</span><span class="w"> </span><span class="p">(</span><span class="n">Row</span><span class="w"> </span><span class="n">row</span><span class="p">:</span><span class="w"> </span><span class="n">table</span><span class="p">)</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">age</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getInt</span><span class="p">(</span><span class="s">"age"</span><span class="p">);</span> |
| <span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="n">nameIsNull</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">isNull</span><span class="p">(</span><span class="s">"name"</span><span class="p">);</span> |
| <span class="w"> </span><span class="p">...</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>Finally, while rows are usually iterated in the order of the underlying data vectors, but they are also positionable using the <cite>Row#setPosition()</cite> method, so you can skip to a specific row. Row numbers are 0-based.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Row</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">table</span><span class="p">.</span><span class="na">immutableRow</span><span class="p">();</span> |
| <span class="kt">int</span><span class="w"> </span><span class="n">age101</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="na">setPosition</span><span class="p">(</span><span class="mi">101</span><span class="p">);</span><span class="w"> </span><span class="c1">// change position directly to 101</span> |
| </pre></div> |
| </div> |
| <p>Any changes to position are applied to all the columns in the table.</p> |
| <p>Note that you must call <cite>next()</cite>, or <cite>setPosition()</cite> before accessing values via a row. Failure to do so results in a runtime exception.</p> |
| </section> |
| <section id="read-operations-using-rows"> |
| <h3>Read operations using rows<a class="headerlink" href="#read-operations-using-rows" title="Permalink to this heading">#</a></h3> |
| <p>Methods are available for getting values by vector name and vector index, where index is the 0-based position of the vector in the table. For example, assuming ‘age’ is the 13th vector in ‘table’, the following two gets are equivalent:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Row</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">table</span><span class="p">.</span><span class="na">immutableRow</span><span class="p">();</span> |
| <span class="n">r</span><span class="p">.</span><span class="na">next</span><span class="p">();</span><span class="w"> </span><span class="c1">// position the row at the first value</span> |
| <span class="kt">int</span><span class="w"> </span><span class="n">age1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="na">get</span><span class="p">(</span><span class="s">"age"</span><span class="p">);</span><span class="w"> </span><span class="c1">// gets the value of vector named 'age' in the table at row 0</span> |
| <span class="kt">int</span><span class="w"> </span><span class="n">age2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="na">get</span><span class="p">(</span><span class="mi">12</span><span class="p">);</span><span class="w"> </span><span class="c1">// gets the value of the 13th vector in the table at row 0</span> |
| </pre></div> |
| </div> |
| <p>You can also get value using a nullable <code class="docutils literal notranslate"><span class="pre">ValueHolder</span></code>. For example:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">NullableIntHolder</span><span class="w"> </span><span class="n">holder</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">NullableIntHolder</span><span class="p">();</span> |
| <span class="kt">int</span><span class="w"> </span><span class="n">b</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getInt</span><span class="p">(</span><span class="s">"age"</span><span class="p">,</span><span class="w"> </span><span class="n">holder</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>This can be used to retrieve values without creating a new Object for each.</p> |
| <p>In addition to getting values, you can check if a value is null using <cite>isNull()</cite>. This is important if the vector contains any nulls, as asking for a value from a vector can cause NullPointerExceptions in some cases.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="kt">boolean</span><span class="w"> </span><span class="n">name0isNull</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">isNull</span><span class="p">(</span><span class="s">"name"</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>You can also get the current row number:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span><span class="w"> </span><span class="n">row</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getRowNumber</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="reading-values-as-objects"> |
| <h3>Reading values as Objects<a class="headerlink" href="#reading-values-as-objects" title="Permalink to this heading">#</a></h3> |
| <p>For any given vector type, the basic <em>get()</em> method returns a primitive value wherever possible. For example, <em>getTimeStampMicro()</em> returns a long value that encodes the timestamp. To get the LocalDateTime object representing that timestamp in Java, another method with ‘Obj’ appended to the name is provided. For example:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="kt">long</span><span class="w"> </span><span class="n">ts</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getTimeStampMicro</span><span class="p">();</span> |
| <span class="n">LocalDateTime</span><span class="w"> </span><span class="n">tsObject</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getTimeStampMicroObj</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| <p>The exception to this naming scheme is for complex vector types (List, Map, Schema, Union, DenseUnion, and ExtensionType). These always return objects rather than primitives so no “Obj” extension is required. It is expected that some users may subclass <code class="docutils literal notranslate"><span class="pre">Row</span></code> to add getters that are more specific to their needs.</p> |
| </section> |
| <section id="reading-varchars-and-largevarchars"> |
| <h3>Reading VarChars and LargeVarChars<a class="headerlink" href="#reading-varchars-and-largevarchars" title="Permalink to this heading">#</a></h3> |
| <p>Strings in arrow are represented as byte arrays encoded with the UTF-8 charset. You can get either a String result or the actual byte array.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="kt">byte</span><span class="o">[]</span><span class="w"> </span><span class="n">b</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getVarChar</span><span class="p">(</span><span class="s">"first_name"</span><span class="p">);</span> |
| <span class="n">String</span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">row</span><span class="p">.</span><span class="na">getVarCharObj</span><span class="p">(</span><span class="s">"first_name"</span><span class="p">);</span><span class="w"> </span><span class="c1">// uses the default encoding (UTF-8)</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="converting-a-table-to-a-vectorschemaroot"> |
| <h3>Converting a Table to a VectorSchemaRoot<a class="headerlink" href="#converting-a-table-to-a-vectorschemaroot" title="Permalink to this heading">#</a></h3> |
| <p>Tables can be converted to vector schema roots using the <em>toVectorSchemaRoot()</em> method. Buffers are transferred to the vector schema root and the source table is cleared.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">VectorSchemaRoot</span><span class="w"> </span><span class="n">root</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">myTable</span><span class="p">.</span><span class="na">toVectorSchemaRoot</span><span class="p">();</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="working-with-the-c-data-interface"> |
| <h3>Working with the C-Data interface<a class="headerlink" href="#working-with-the-c-data-interface" title="Permalink to this heading">#</a></h3> |
| <p>The ability to work with native code is required for many Arrow features. This section describes how tables can be be exported for use with native code</p> |
| <p>Exporting works by converting the data to a <code class="docutils literal notranslate"><span class="pre">VectorSchemaRoot</span></code> instance and using the existing facilities to transfer the data. You could do it yourself, but that isn’t ideal because conversion to a vector schema root breaks the immutability guarantees. Using the <cite>exportTable()</cite> methods in the <a class="reference external" href="https://arrow.apache.org/docs/java/reference/org/apache/arrow/c/Data.html">Data</a> class avoids this concern.</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Data</span><span class="p">.</span><span class="na">exportTable</span><span class="p">(</span><span class="n">bufferAllocator</span><span class="p">,</span><span class="w"> </span><span class="n">table</span><span class="p">,</span><span class="w"> </span><span class="n">dictionaryProvider</span><span class="p">,</span><span class="w"> </span><span class="n">outArrowArray</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>If the table contains dictionary-encoded vectors and was constructed with a <code class="docutils literal notranslate"><span class="pre">DictionaryProvider</span></code>, the provider argument to <cite>exportTable()</cite> can be omitted and the table’s provider attribute will be used:</p> |
| <div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="n">Data</span><span class="p">.</span><span class="na">exportTable</span><span class="p">(</span><span class="n">bufferAllocator</span><span class="p">,</span><span class="w"> </span><span class="n">table</span><span class="p">,</span><span class="w"> </span><span class="n">outArrowArray</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| </section> |
| </section> |
| </section> |
| |
| |
| </article> |
| |
| |
| |
| |
| |
| <footer class="prev-next-footer"> |
| |
| <div class="prev-next-area"> |
| <a class="left-prev" |
| href="vector_schema_root.html" |
| title="previous page"> |
| <i class="fa-solid fa-angle-left"></i> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">previous</p> |
| <p class="prev-next-title">Tabular Data</p> |
| </div> |
| </a> |
| <a class="right-next" |
| href="ipc.html" |
| title="next page"> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">next</p> |
| <p class="prev-next-title">Reading/Writing IPC formats</p> |
| </div> |
| <i class="fa-solid fa-angle-right"></i> |
| </a> |
| </div> |
| </footer> |
| |
| </div> |
| |
| |
| |
| <div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner"> |
| |
| |
| <div class="sidebar-secondary-item"> |
| <div |
| id="pst-page-navigation-heading-2" |
| class="page-toc tocsection onthispage"> |
| <i class="fa-solid fa-list"></i> On this page |
| </div> |
| <nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2"> |
| <ul class="visible nav section-nav flex-column"> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#mutation-in-table-and-vectorschemaroot">Mutation in Table and VectorSchemaRoot</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#features-and-limitations">Features and limitations</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#the-table-api">The Table API</a><ul class="visible nav section-nav flex-column"> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#creating-a-table-from-a-vectorschemaroot">Creating a Table from a VectorSchemaRoot</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#creating-a-table-from-fieldvectors">Creating a Table from FieldVectors</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#creating-tables-with-dictionary-encoded-vectors">Creating Tables with dictionary-encoded vectors</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#freeing-memory-explicitly">Freeing memory explicitly</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#getting-the-schema">Getting the schema</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#adding-and-removing-vectors">Adding and removing vectors</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#slicing-tables">Slicing tables</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#using-fieldreaders">Using FieldReaders</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#row-operations">Row operations</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#getting-a-row">Getting a row</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#moving-from-row-to-row">Moving from row-to-row</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#read-operations-using-rows">Read operations using rows</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#reading-values-as-objects">Reading values as Objects</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#reading-varchars-and-largevarchars">Reading VarChars and LargeVarChars</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#converting-a-table-to-a-vectorschemaroot">Converting a Table to a VectorSchemaRoot</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#working-with-the-c-data-interface">Working with the C-Data interface</a></li> |
| </ul> |
| </li> |
| </ul> |
| </nav></div> |
| |
| <div class="sidebar-secondary-item"> |
| |
| |
| <div class="tocsection editthispage"> |
| <a href="https://github.com/apache/arrow/edit/main/docs/source/java/table.rst"> |
| <i class="fa-solid fa-pencil"></i> |
| |
| |
| |
| Edit on GitHub |
| |
| |
| </a> |
| </div> |
| </div> |
| |
| </div></div> |
| |
| |
| </div> |
| <footer class="bd-footer-content"> |
| |
| </footer> |
| |
| </main> |
| </div> |
| </div> |
| |
| <!-- Scripts loaded after <body> so the DOM is not blocked --> |
| <script src="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae"></script> |
| <script src="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae"></script> |
| |
| <footer class="bd-footer"> |
| <div class="bd-footer__inner bd-page-width"> |
| |
| <div class="footer-items__start"> |
| |
| <div class="footer-item"> |
| |
| <p class="copyright"> |
| |
| © Copyright 2016-2024 Apache Software Foundation. |
| Apache Arrow, Arrow, Apache, the Apache feather logo, and the Apache Arrow project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries. |
| <br/> |
| |
| </p> |
| </div> |
| |
| <div class="footer-item"> |
| |
| <p class="sphinx-version"> |
| Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 6.2.0. |
| <br/> |
| </p> |
| </div> |
| |
| </div> |
| |
| |
| |
| <div class="footer-items__end"> |
| |
| <div class="footer-item"> |
| <p class="theme-version"> |
| Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.2. |
| </p></div> |
| |
| </div> |
| |
| </div> |
| |
| </footer> |
| </body> |
| </html> |
