| |
| <!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="viewport" content="width=device-width, initial-scale=1" /> |
| |
| <title>Arrow Flight RPC — Apache Arrow v22.0.0.dev226</title> |
| |
| |
| |
| <script data-cfasync="false"> |
| document.documentElement.dataset.mode = localStorage.getItem("mode") || ""; |
| document.documentElement.dataset.theme = localStorage.getItem("theme") || ""; |
| </script> |
| <!-- |
| this give us a css class that will be invisible only if js is disabled |
| --> |
| <noscript> |
| <style> |
| .pst-js-only { display: none !important; } |
| |
| </style> |
| </noscript> |
| |
| <!-- Loaded before other Sphinx assets --> |
| <link href="../_static/styles/theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" /> |
| <link href="../_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" /> |
| |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" /> |
| <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" /> |
| <link rel="stylesheet" type="text/css" href="../_static/sphinx-design.min.css?v=95c83b7e" /> |
| <link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css?v=8dcd28dc" /> |
| |
| <!-- So that users can add custom icons --> |
| <script src="../_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script> |
| <!-- Pre-loaded scripts that we'll load fully later --> |
| <link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" /> |
| <link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" /> |
| |
| <script src="../_static/documentation_options.js?v=a6fd041c"></script> |
| <script src="../_static/doctools.js?v=9bcbadda"></script> |
| <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> |
| <script src="../_static/clipboard.min.js?v=a7894cd8"></script> |
| <script src="../_static/copybutton.js?v=3bb21c8c"></script> |
| <script src="../_static/design-tabs.js?v=f930bc37"></script> |
| <script type="module" src="https://cdn.jsdelivr.net/npm/mermaid@11.2.0/dist/mermaid.esm.min.mjs"></script> |
| <script type="module" src="https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0.1.4/dist/mermaid-layout-elk.esm.min.mjs"></script> |
| <script type="module">import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11.2.0/dist/mermaid.esm.min.mjs";import elkLayouts from "https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0.1.4/dist/mermaid-layout-elk.esm.min.mjs";mermaid.registerLayoutLoaders(elkLayouts);mermaid.initialize({startOnLoad:false});</script> |
| <script type="module"> |
| import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11.2.0/dist/mermaid.esm.min.mjs"; |
| window.addEventListener("load", () => mermaid.run()); |
| </script> |
| <script>DOCUMENTATION_OPTIONS.pagename = 'format/Flight';</script> |
| <script> |
| DOCUMENTATION_OPTIONS.theme_version = '0.16.1'; |
| 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/format/Flight.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="Arrow Flight SQL" href="FlightSql.html" /> |
| <link rel="prev" title="Dissociated IPC Protocol" href="DissociatedIPC.html" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <meta name="docsearch:language" content="en"/> |
| <meta name="docsearch:version" content="22.0.0.dev226" /> |
| |
| <!-- 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=""> |
| |
| |
| |
| <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div> |
| |
| <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> |
| |
| |
| <dialog id="pst-search-dialog"> |
| |
| <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" |
| 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> |
| </dialog> |
| |
| <div class="pst-async-banner-revealer d-none"> |
| <aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside> |
| </div> |
| |
| |
| <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none"> |
| <div class="bd-header__inner bd-page-width"> |
| <button class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation"> |
| <span class="fa-solid fa-bars"></span> |
| </button> |
| |
| |
| <div class=" 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 v22.0.0.dev226 - Home"/> |
| <img src="../_static/arrow-dark.png" class="logo__image only-dark pst-js-only" alt="Apache Arrow v22.0.0.dev226 - Home"/> |
| |
| |
| </a></div> |
| |
| </div> |
| |
| <div class=" navbar-header-items"> |
| |
| <div class="me-auto navbar-header-items__center"> |
| |
| <div class="navbar-item"> |
| <nav> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item current active"> |
| <a class="nav-link nav-internal" href="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 "> |
| <a class="nav-link nav-internal" href="../implementations.html"> |
| Implementations |
| </a> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| </div> |
| |
| |
| <div class="navbar-header-items__end"> |
| |
| <div class="navbar-item navbar-persistent--container"> |
| |
| |
| <button class="btn search-button-field search-button__button pst-js-only" 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> |
| </div> |
| |
| |
| <div class="navbar-item"><div class="kapa-ai-bot"> |
| <script |
| async |
| src="https://widget.kapa.ai/kapa-widget.bundle.js" |
| data-website-id="9db461d5-ac77-4b3f-a5c5-75efa78339d2" |
| data-project-name="Apache Arrow" |
| data-project-color="#000000" |
| data-project-logo="https://arrow.apache.org/img/arrow-logo_chevrons_white-txt_black-bg.png" |
| data-modal-disclaimer="This is a custom LLM with access to all [Arrow documentation](https://arrow.apache.org/docs/). Please include the language you are using in your question, e.g., Python, C++, Java, R, etc." |
| data-consent-required="true" |
| data-user-analytics-cookie-enabled="false" |
| data-consent-screen-disclaimer="By clicking "I agree, let's chat", you consent to the use of the AI assistant in accordance with kapa.ai's [Privacy Policy](https://www.kapa.ai/content/privacy-policy). This service uses reCAPTCHA, which requires your consent to Google's [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms). By proceeding, you explicitly agree to both kapa.ai's and Google's privacy policies." |
| ></script> |
| |
| </div> |
| |
| </div> |
| |
| <div class="navbar-item"> |
| <div class="version-switcher__container dropdown pst-js-only"> |
| <button id="pst-version-switcher-button-2" |
| type="button" |
| class="version-switcher__button btn btn-sm 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></div> |
| |
| <div class="navbar-item"> |
| |
| <button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i> |
| <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i> |
| <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i> |
| </button></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://www.linkedin.com/company/apache-arrow/" title="LinkedIn" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-linkedin fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">LinkedIn</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://bsky.app/profile/arrow.apache.org" title="BlueSky" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-bluesky fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">BlueSky</span></a> |
| </li> |
| </ul></div> |
| |
| </div> |
| |
| </div> |
| |
| |
| <div class="navbar-persistent--mobile"> |
| |
| <button class="btn search-button-field search-button__button pst-js-only" 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> |
| </div> |
| |
| |
| |
| <button class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page"> |
| <span class="fa-solid fa-outdent"></span> |
| </button> |
| |
| </div> |
| |
| </header> |
| |
| |
| <div class="bd-container"> |
| <div class="bd-container__inner bd-page-width"> |
| |
| |
| |
| <dialog id="pst-primary-sidebar-modal"></dialog> |
| <div id="pst-primary-sidebar" 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> |
| <ul class="bd-navbar-elements navbar-nav"> |
| |
| <li class="nav-item current active"> |
| <a class="nav-link nav-internal" href="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 "> |
| <a class="nav-link nav-internal" href="../implementations.html"> |
| Implementations |
| </a> |
| </li> |
| |
| </ul> |
| </nav></div> |
| |
| |
| </div> |
| |
| |
| |
| <div class="sidebar-header-items__end"> |
| |
| <div class="navbar-item"><div class="kapa-ai-bot"> |
| <script |
| async |
| src="https://widget.kapa.ai/kapa-widget.bundle.js" |
| data-website-id="9db461d5-ac77-4b3f-a5c5-75efa78339d2" |
| data-project-name="Apache Arrow" |
| data-project-color="#000000" |
| data-project-logo="https://arrow.apache.org/img/arrow-logo_chevrons_white-txt_black-bg.png" |
| data-modal-disclaimer="This is a custom LLM with access to all [Arrow documentation](https://arrow.apache.org/docs/). Please include the language you are using in your question, e.g., Python, C++, Java, R, etc." |
| data-consent-required="true" |
| data-user-analytics-cookie-enabled="false" |
| data-consent-screen-disclaimer="By clicking "I agree, let's chat", you consent to the use of the AI assistant in accordance with kapa.ai's [Privacy Policy](https://www.kapa.ai/content/privacy-policy). This service uses reCAPTCHA, which requires your consent to Google's [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms). By proceeding, you explicitly agree to both kapa.ai's and Google's privacy policies." |
| ></script> |
| |
| </div> |
| |
| </div> |
| |
| <div class="navbar-item"> |
| <div class="version-switcher__container dropdown pst-js-only"> |
| <button id="pst-version-switcher-button-3" |
| type="button" |
| class="version-switcher__button btn btn-sm 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></div> |
| |
| <div class="navbar-item"> |
| |
| <button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip"> |
| <i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i> |
| <i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i> |
| <i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i> |
| </button></div> |
| |
| <div class="navbar-item"><ul class="navbar-icon-links" |
| aria-label="Icon Links"> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://github.com/apache/arrow" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">GitHub</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://www.linkedin.com/company/apache-arrow/" title="LinkedIn" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-linkedin fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">LinkedIn</span></a> |
| </li> |
| <li class="nav-item"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <a href="https://bsky.app/profile/arrow.apache.org" title="BlueSky" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-bluesky fa-lg" aria-hidden="true"></i> |
| <span class="sr-only">BlueSky</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="Intro.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="Columnar.html">Arrow Columnar Format</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="Versioning.html">Format Versioning and Stability</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="Changing.html">Changing the Apache Arrow Format Specification</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="CanonicalExtensions.html">Canonical Extension Types</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="Other.html">Other Data Structures</a></li> |
| <li class="toctree-l1 has-children"><a class="reference internal" href="CDataInterface.html">The Arrow C data interface</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul> |
| <li class="toctree-l2"><a class="reference internal" href="CDataInterface/PyCapsuleInterface.html">The Arrow PyCapsule Interface</a></li> |
| </ul> |
| </details></li> |
| <li class="toctree-l1"><a class="reference internal" href="CStreamInterface.html">The Arrow C stream interface</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="CDeviceDataInterface.html">The Arrow C Device data interface</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="StatisticsSchema.html">Statistics schema</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="DissociatedIPC.html">Dissociated IPC Protocol</a></li> |
| <li class="toctree-l1 current active"><a class="current reference internal" href="#">Arrow Flight RPC</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="FlightSql.html">Arrow Flight SQL</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="ADBC.html">ADBC: Arrow Database Connectivity</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="Integration.html">Integration Testing</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="Glossary.html">Glossary</a></li> |
| </ul> |
| </div> |
| </nav></div> |
| </div> |
| |
| |
| <div class="sidebar-primary-items__end sidebar-primary__section"> |
| <div class="sidebar-primary-item"> |
| <div id="ethical-ad-placement" |
| class="flat" |
| data-ea-publisher="readthedocs" |
| data-ea-type="readthedocs-sidebar" |
| data-ea-manual="true"> |
| </div></div> |
| </div> |
| |
| |
| </div> |
| |
| <main id="main-content" class="bd-main" role="main"> |
| |
| |
| <div class="bd-content"> |
| <div class="bd-article-container"> |
| |
| <div class="bd-header-article d-print-none"> |
| <div class="header-article-items header-article__inner"> |
| |
| <div class="header-article-items__start"> |
| |
| <div class="header-article-item"> |
| |
| <nav aria-label="Breadcrumb" class="d-print-none"> |
| <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">Specifications</a></li> |
| |
| <li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">Arrow Flight RPC</span></li> |
| </ul> |
| </nav> |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| |
| |
| |
| <div id="searchbox"></div> |
| <article class="bd-article"> |
| |
| <section id="arrow-flight-rpc"> |
| <span id="flight-rpc"></span><h1>Arrow Flight RPC<a class="headerlink" href="#arrow-flight-rpc" title="Link to this heading">#</a></h1> |
| <p>Arrow Flight is an RPC framework for high-performance data services |
| based on Arrow data, and is built on top of <a class="reference external" href="https://grpc.io/">gRPC</a> and the <a class="reference internal" href="IPC.html"><span class="doc">IPC |
| format</span></a>.</p> |
| <p>Flight is organized around streams of Arrow record batches, being |
| either downloaded from or uploaded to another service. A set of |
| metadata methods offers discovery and introspection of streams, as |
| well as the ability to implement application-specific methods.</p> |
| <p>Methods and message wire formats are defined by <a class="reference external" href="https://developers.google.com/protocol-buffers/">Protobuf</a>, enabling |
| interoperability with clients that may support gRPC and Arrow |
| separately, but not Flight. However, Flight implementations include |
| further optimizations to avoid overhead in usage of Protobuf (mostly |
| around avoiding excessive memory copies).</p> |
| <section id="rpc-methods-and-request-patterns"> |
| <h2>RPC Methods and Request Patterns<a class="headerlink" href="#rpc-methods-and-request-patterns" title="Link to this heading">#</a></h2> |
| <p>Flight defines a set of RPC methods for uploading/downloading data, |
| retrieving metadata about a data stream, listing available data |
| streams, and for implementing application-specific RPC methods. A |
| Flight service implements some subset of these methods, while a Flight |
| client can call any of these methods.</p> |
| <p>Data streams are identified by descriptors (the <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code> |
| message), which are either a path or an arbitrary binary command. For |
| instance, the descriptor may encode a SQL query, a path to a file on a |
| distributed file system, or even a pickled Python object; the |
| application can use this message as it sees fit.</p> |
| <p>Thus, one Flight client can connect to any service and perform basic |
| operations. To facilitate this, Flight services are <em>expected</em> to |
| support some common request patterns, described next. Of course, |
| applications may ignore compatibility and simply treat the Flight RPC |
| methods as low-level building blocks for their own purposes.</p> |
| <p>See <a class="reference internal" href="#protocol-buffer-definitions">Protocol Buffer Definitions</a> for full details on the methods and |
| messages involved.</p> |
| <section id="downloading-data"> |
| <h3>Downloading Data<a class="headerlink" href="#downloading-data" title="Link to this heading">#</a></h3> |
| <p>A client that wishes to download the data would:</p> |
| <figure class="align-default" id="id1"> |
| <object data="../_images/mermaid-d785eba82bd4f2ca4f891cf02e983e82b999cc5b.svg" type="image/svg+xml"> |
| <p class="warning">%% Licensed to the Apache Software Foundation (ASF) under one |
| %% or more contributor license agreements. See the NOTICE file |
| %% distributed with this work for additional information |
| %% regarding copyright ownership. The ASF licenses this file |
| %% to you under the Apache License, Version 2.0 (the |
| %% "License"); you may not use this file except in compliance |
| %% with the License. You may obtain a copy of the License at |
| %% |
| %% http://www.apache.org/licenses/LICENSE-2.0 |
| %% |
| %% Unless required by applicable law or agreed to in writing, |
| %% software distributed under the License is distributed on an |
| %% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| %% KIND, either express or implied. See the License for the |
| %% specific language governing permissions and limitations |
| %% under the License. |
| |
| sequenceDiagram |
| autonumber |
| |
| participant Client |
| participant Metadata Server |
| participant Data Server |
| Client->>Metadata Server: GetFlightInfo(FlightDescriptor) |
| Metadata Server->>Client: FlightInfo{endpoints: [FlightEndpoint{ticket: Ticket}, …]} |
| Note over Client, Data Server: This may be parallelized |
| loop for each endpoint in FlightInfo.endpoints |
| Client->>Data Server: DoGet(Ticket) |
| Data Server->>Client: stream of FlightData |
| end</p></object> |
| <figcaption> |
| <p><span class="caption-text">Retrieving data via <code class="docutils literal notranslate"><span class="pre">DoGet</span></code>.</span><a class="headerlink" href="#id1" title="Link to this image">#</a></p> |
| </figcaption> |
| </figure> |
| <ol class="arabic"> |
| <li><p>Construct or acquire a <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code> for the data set they |
| are interested in.</p> |
| <p>A client may know what descriptor they want already, or they may |
| use methods like <code class="docutils literal notranslate"><span class="pre">ListFlights</span></code> to discover them.</p> |
| </li> |
| <li><p>Call <code class="docutils literal notranslate"><span class="pre">GetFlightInfo(FlightDescriptor)</span></code> to get a <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code> |
| message.</p> |
| <p>Flight does not require that data live on the same server as |
| metadata. Hence, <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code> contains details on where the data |
| is located, so the client can go fetch the data from an appropriate |
| server. This is encoded as a series of <code class="docutils literal notranslate"><span class="pre">FlightEndpoint</span></code> messages |
| inside <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code>. Each endpoint represents some location that |
| contains a subset of the response data.</p> |
| <p>An endpoint contains a list of locations (server addresses) where |
| this data can be retrieved from, and a <code class="docutils literal notranslate"><span class="pre">Ticket</span></code>, an opaque binary |
| token that the server will use to identify the data being |
| requested.</p> |
| <p>If <code class="docutils literal notranslate"><span class="pre">FlightInfo.ordered</span></code> is true, this signals there is some order |
| between data from different endpoints. Clients should produce the |
| same results as if the data returned from each of the endpoints was |
| concatenated, in order, from front to back.</p> |
| <p>If <code class="docutils literal notranslate"><span class="pre">FlightInfo.ordered</span></code> is false, the client may return data |
| from any of the endpoints in arbitrary order. Data from any |
| specific endpoint must be returned in order, but the data from |
| different endpoints may be interleaved to allow parallel fetches.</p> |
| <p>Note that since some clients may ignore <code class="docutils literal notranslate"><span class="pre">FlightInfo.ordered</span></code>, if |
| ordering is important and client support cannot be ensured, |
| servers should return a single endpoint.</p> |
| <p>The response also contains other metadata, like the schema, and |
| optionally an estimate of the dataset size.</p> |
| </li> |
| <li><p>Consume each endpoint returned by the server.</p> |
| <p>To consume an endpoint, the client should connect to one of the |
| locations in the endpoint, then call <code class="docutils literal notranslate"><span class="pre">DoGet(Ticket)</span></code> with the |
| ticket in the endpoint. This will give the client a stream of Arrow |
| record batches.</p> |
| <p>If the server wishes to indicate that the data is on the local |
| server and not a different location, then it can return an empty |
| list of locations. The client can then reuse the existing |
| connection to the original server to fetch data. Otherwise, the |
| client must connect to one of the indicated locations.</p> |
| <p>The server may list “itself” as a location alongside other server |
| locations. Normally this requires the server to know its public |
| address, but it may also use the special URI string |
| <code class="docutils literal notranslate"><span class="pre">arrow-flight-reuse-connection://?</span></code> to tell clients that they may |
| reuse an existing connection to the same server, without having to |
| be able to name itself. See <a class="reference internal" href="#connection-reuse">Connection Reuse</a> below.</p> |
| <p>In this way, the locations inside an endpoint can also be thought |
| of as performing look-aside load balancing or service discovery |
| functions. And the endpoints can represent data that is partitioned |
| or otherwise distributed.</p> |
| <p>The client must consume all endpoints to retrieve the complete data |
| set. The client can consume endpoints in any order, or even in |
| parallel, or distribute the endpoints among multiple machines for |
| consumption; this is up to the application to implement. The client |
| can also use <code class="docutils literal notranslate"><span class="pre">FlightInfo.ordered</span></code>. See the previous item for |
| details of <code class="docutils literal notranslate"><span class="pre">FlightInfo.ordered</span></code>.</p> |
| <p>Each endpoint may have expiration time |
| (<code class="docutils literal notranslate"><span class="pre">FlightEndpoint.expiration_time</span></code>). If an endpoint has expiration |
| time, the client can get data multiple times by <code class="docutils literal notranslate"><span class="pre">DoGet</span></code> until the |
| expiration time is reached. Otherwise, it is application-defined |
| whether <code class="docutils literal notranslate"><span class="pre">DoGet</span></code> requests may be retried. The expiration time is |
| represented as <a class="reference external" href="https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp">google.protobuf.Timestamp</a>.</p> |
| <p>If the expiration time is short, the client may be able to extend |
| the expiration time by <code class="docutils literal notranslate"><span class="pre">RenewFlightEndpoint</span></code> action. The client |
| need to use <code class="docutils literal notranslate"><span class="pre">DoAction</span></code> with <code class="docutils literal notranslate"><span class="pre">RenewFlightEndpoint</span></code> action type |
| to extend the expiration time. <code class="docutils literal notranslate"><span class="pre">Action.body</span></code> must be |
| <code class="docutils literal notranslate"><span class="pre">RenewFlightEndpointRequest</span></code> that has <code class="docutils literal notranslate"><span class="pre">FlightEndpoint</span></code> to be |
| renewed.</p> |
| <p>The client may be able to cancel the returned <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code> by |
| <code class="docutils literal notranslate"><span class="pre">CancelFlightInfo</span></code> action. The client need to use <code class="docutils literal notranslate"><span class="pre">DoAction</span></code> |
| with <code class="docutils literal notranslate"><span class="pre">CancelFlightInfo</span></code> action type to cancel the <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code>.</p> |
| </li> |
| </ol> |
| </section> |
| <section id="downloading-data-by-running-a-heavy-query"> |
| <h3>Downloading Data by Running a Heavy Query<a class="headerlink" href="#downloading-data-by-running-a-heavy-query" title="Link to this heading">#</a></h3> |
| <p>A client may need to request a heavy query to download |
| data. However, <code class="docutils literal notranslate"><span class="pre">GetFlightInfo</span></code> doesn’t return until the query |
| completes, so the client is blocked. In this situation, the client |
| can use <code class="docutils literal notranslate"><span class="pre">PollFlightInfo</span></code> instead of <code class="docutils literal notranslate"><span class="pre">GetFlightInfo</span></code>:</p> |
| <figure class="align-default" id="id2"> |
| <object data="../_images/mermaid-ebbcd076c75e58734773c06de07db3d1fcb27d86.svg" type="image/svg+xml"> |
| <p class="warning">%% Licensed to the Apache Software Foundation (ASF) under one |
| %% or more contributor license agreements. See the NOTICE file |
| %% distributed with this work for additional information |
| %% regarding copyright ownership. The ASF licenses this file |
| %% to you under the Apache License, Version 2.0 (the |
| %% "License"); you may not use this file except in compliance |
| %% with the License. You may obtain a copy of the License at |
| %% |
| %% http://www.apache.org/licenses/LICENSE-2.0 |
| %% |
| %% Unless required by applicable law or agreed to in writing, |
| %% software distributed under the License is distributed on an |
| %% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| %% KIND, either express or implied. See the License for the |
| %% specific language governing permissions and limitations |
| %% under the License. |
| |
| sequenceDiagram |
| autonumber |
| |
| participant Client |
| participant Metadata Server |
| participant Data Server |
| Client->>Metadata Server: PollFlightInfo(FlightDescriptor) |
| Metadata Server->>Client: PollInfo{descriptor: FlightDescriptor', ...} |
| Client->>Metadata Server: PollFlightInfo(FlightDescriptor') |
| Metadata Server->>Client: PollInfo{descriptor: FlightDescriptor'', ...} |
| Client->>Metadata Server: PollFlightInfo(FlightDescriptor'') |
| Metadata Server->>Client: PollInfo{descriptor: null, info: FlightInfo{endpoints: [FlightEndpoint{ticket: Ticket}, …]} |
| Note over Client, Data Server: This may be parallelized |
| Note over Client, Data Server: Some endpoints may be processed while polling |
| loop for each endpoint in FlightInfo.endpoints |
| Client->>Data Server: DoGet(Ticket) |
| Data Server->>Client: stream of FlightData |
| end</p></object> |
| <figcaption> |
| <p><span class="caption-text">Polling a long-running query by <code class="docutils literal notranslate"><span class="pre">PollFlightInfo</span></code>.</span><a class="headerlink" href="#id2" title="Link to this image">#</a></p> |
| </figcaption> |
| </figure> |
| <ol class="arabic"> |
| <li><p>Construct or acquire a <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code>, as before.</p></li> |
| <li><p>Call <code class="docutils literal notranslate"><span class="pre">PollFlightInfo(FlightDescriptor)</span></code> to get a <code class="docutils literal notranslate"><span class="pre">PollInfo</span></code> |
| message.</p> |
| <p>A server should respond as quickly as possible on the first |
| call. So the client shouldn’t wait for the first <code class="docutils literal notranslate"><span class="pre">PollInfo</span></code> |
| response.</p> |
| <p>If the query isn’t finished, <code class="docutils literal notranslate"><span class="pre">PollInfo.flight_descriptor</span></code> has a |
| <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code>. The client should use the descriptor (not the |
| original <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code>) to call the next |
| <code class="docutils literal notranslate"><span class="pre">PollFlightInfo()</span></code>. A server should recognize a |
| <code class="docutils literal notranslate"><span class="pre">PollInfo.flight_descriptor</span></code> that is not necessarily the latest |
| in case the client misses an update in between.</p> |
| <p>If the query is finished, <code class="docutils literal notranslate"><span class="pre">PollInfo.flight_descriptor</span></code> is |
| unset.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">PollInfo.info</span></code> is the currently available results so far. It’s |
| a complete <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code> each time not just the delta between the |
| previous and current <code class="docutils literal notranslate"><span class="pre">FlightInfo</span></code>. A server should only append to |
| the endpoints in <code class="docutils literal notranslate"><span class="pre">PollInfo.info</span></code> each time. So the client can |
| run <code class="docutils literal notranslate"><span class="pre">DoGet(Ticket)</span></code> with the <code class="docutils literal notranslate"><span class="pre">Ticket</span></code> in the <code class="docutils literal notranslate"><span class="pre">PollInfo.info</span></code> |
| even when the query isn’t finished yet. <code class="docutils literal notranslate"><span class="pre">FlightInfo.ordered</span></code> is |
| also valid.</p> |
| <p>A server should not respond until the result would be different |
| from last time. That way, the client can “long poll” for updates |
| without constantly making requests. Clients can set a short timeout |
| to avoid blocking calls if desired.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">PollInfo.progress</span></code> may be set. It represents progress of the |
| query. If it’s set, the value must be in <code class="docutils literal notranslate"><span class="pre">[0.0,</span> <span class="pre">1.0]</span></code>. The value |
| is not necessarily monotonic or nondecreasing. A server may respond by |
| only updating the <code class="docutils literal notranslate"><span class="pre">PollInfo.progress</span></code> value, though it shouldn’t |
| spam the client with updates.</p> |
| <p><code class="docutils literal notranslate"><span class="pre">PollInfo.timestamp</span></code> is the expiration time for this |
| request. After this passes, a server might not accept the poll |
| descriptor anymore and the query may be cancelled. This may be |
| updated on a call to <code class="docutils literal notranslate"><span class="pre">PollFlightInfo</span></code>. The expiration time is |
| represented as <a class="reference external" href="https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp">google.protobuf.Timestamp</a>.</p> |
| <p>A client may be able to cancel the query by the |
| <code class="docutils literal notranslate"><span class="pre">CancelFlightInfo</span></code> action.</p> |
| <p>A server should return an error status instead of a response if the |
| query fails. The client should not poll the request except for |
| <code class="docutils literal notranslate"><span class="pre">TIMED_OUT</span></code> and <code class="docutils literal notranslate"><span class="pre">UNAVAILABLE</span></code>, which may not originate from the |
| server.</p> |
| </li> |
| <li><p>Consume each endpoint returned by the server, as before.</p></li> |
| </ol> |
| </section> |
| <section id="uploading-data"> |
| <h3>Uploading Data<a class="headerlink" href="#uploading-data" title="Link to this heading">#</a></h3> |
| <p>To upload data, a client would:</p> |
| <figure class="align-default" id="id3"> |
| <object data="../_images/mermaid-67d0aeb144e6323ffb0fc64ce1618e431fe1d163.svg" type="image/svg+xml"> |
| <p class="warning">%% Licensed to the Apache Software Foundation (ASF) under one |
| %% or more contributor license agreements. See the NOTICE file |
| %% distributed with this work for additional information |
| %% regarding copyright ownership. The ASF licenses this file |
| %% to you under the Apache License, Version 2.0 (the |
| %% "License"); you may not use this file except in compliance |
| %% with the License. You may obtain a copy of the License at |
| %% |
| %% http://www.apache.org/licenses/LICENSE-2.0 |
| %% |
| %% Unless required by applicable law or agreed to in writing, |
| %% software distributed under the License is distributed on an |
| %% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| %% KIND, either express or implied. See the License for the |
| %% specific language governing permissions and limitations |
| %% under the License. |
| |
| sequenceDiagram |
| autonumber |
| |
| participant Client |
| participant Server |
| Note right of Client: The first FlightData includes a FlightDescriptor |
| Client->>Server: DoPut(FlightData) |
| Client->>Server: stream of FlightData |
| Server->>Client: PutResult{app_metadata}</p></object> |
| <figcaption> |
| <p><span class="caption-text">Uploading data via <code class="docutils literal notranslate"><span class="pre">DoPut</span></code>.</span><a class="headerlink" href="#id3" title="Link to this image">#</a></p> |
| </figcaption> |
| </figure> |
| <ol class="arabic"> |
| <li><p>Construct or acquire a <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code>, as before.</p></li> |
| <li><p>Call <code class="docutils literal notranslate"><span class="pre">DoPut(FlightData)</span></code> and upload a stream of Arrow record |
| batches.</p> |
| <p>The <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code> is included with the first message so the |
| server can identify the dataset.</p> |
| </li> |
| </ol> |
| <p><code class="docutils literal notranslate"><span class="pre">DoPut</span></code> allows the server to send response messages back to the |
| client with custom metadata. This can be used to implement things like |
| resumable writes (e.g. the server can periodically send a message |
| indicating how many rows have been committed so far).</p> |
| </section> |
| <section id="exchanging-data"> |
| <h3>Exchanging Data<a class="headerlink" href="#exchanging-data" title="Link to this heading">#</a></h3> |
| <p>Some use cases may require uploading and downloading data within a |
| single call. While this can be emulated with multiple calls, this may |
| be difficult if the application is stateful. For instance, the |
| application may wish to implement a call where the client uploads data |
| and the server responds with a transformation of that data; this would |
| require being stateful if implemented using <code class="docutils literal notranslate"><span class="pre">DoGet</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">DoPut</span></code>. Instead, <code class="docutils literal notranslate"><span class="pre">DoExchange</span></code> allows this to be implemented as a |
| single call. A client would:</p> |
| <figure class="align-default" id="id4"> |
| <object data="../_images/mermaid-5394f8aee31905698e8c4b9212160f28f32c61f7.svg" type="image/svg+xml"> |
| <p class="warning">%% Licensed to the Apache Software Foundation (ASF) under one |
| %% or more contributor license agreements. See the NOTICE file |
| %% distributed with this work for additional information |
| %% regarding copyright ownership. The ASF licenses this file |
| %% to you under the Apache License, Version 2.0 (the |
| %% "License"); you may not use this file except in compliance |
| %% with the License. You may obtain a copy of the License at |
| %% |
| %% http://www.apache.org/licenses/LICENSE-2.0 |
| %% |
| %% Unless required by applicable law or agreed to in writing, |
| %% software distributed under the License is distributed on an |
| %% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| %% KIND, either express or implied. See the License for the |
| %% specific language governing permissions and limitations |
| %% under the License. |
| |
| sequenceDiagram |
| autonumber |
| |
| participant Client |
| participant Server |
| Note right of Client: The first FlightData includes a FlightDescriptor |
| Client->>Server: DoExchange(FlightData) |
| par [Client sends data] |
| Client->>Server: stream of FlightData |
| and [Server sends data] |
| Server->>Client: stream of FlightData |
| end</p></object> |
| <figcaption> |
| <p><span class="caption-text">Complex data flow with <code class="docutils literal notranslate"><span class="pre">DoExchange</span></code>.</span><a class="headerlink" href="#id4" title="Link to this image">#</a></p> |
| </figcaption> |
| </figure> |
| <ol class="arabic"> |
| <li><p>Construct or acquire a <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code>, as before.</p></li> |
| <li><p>Call <code class="docutils literal notranslate"><span class="pre">DoExchange(FlightData)</span></code>.</p> |
| <p>The <code class="docutils literal notranslate"><span class="pre">FlightDescriptor</span></code> is included with the first message, as |
| with <code class="docutils literal notranslate"><span class="pre">DoPut</span></code>. At this point, both the client and the server may |
| simultaneously stream data to the other side.</p> |
| </li> |
| </ol> |
| </section> |
| </section> |
| <section id="authentication"> |
| <h2>Authentication<a class="headerlink" href="#authentication" title="Link to this heading">#</a></h2> |
| <p>Flight supports a variety of authentication methods that applications |
| can customize for their needs.</p> |
| <dl> |
| <dt>“Handshake” authentication</dt><dd><p>This is implemented in two parts. At connection time, the client |
| calls the <code class="docutils literal notranslate"><span class="pre">Handshake</span></code> RPC method, and the application-defined |
| authentication handler can exchange any number of messages with its |
| counterpart on the server. The handler then provides a binary |
| token. The Flight client will then include this token in the headers |
| of all future calls, which is validated by the server authentication |
| handler.</p> |
| <p>Applications may use any part of this; for instance, they may ignore |
| the initial handshake and send an externally acquired token (e.g. a |
| bearer token) on each call, or they may establish trust during the |
| handshake and not validate a token for each call, treating the |
| connection as stateful (a “login” pattern).</p> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>Unless a token is validated on every call, this pattern |
| is not secure, especially in the presence of a layer |
| 7 load balancer, as is common with gRPC, or if gRPC |
| transparently reconnects the client.</p> |
| </div> |
| </dd> |
| <dt>Header-based/middleware-based authentication</dt><dd><p>Clients may include custom headers with calls. Custom middleware can |
| then be implemented to validate and accept/reject calls on the |
| server side.</p> |
| </dd> |
| <dt><a class="reference external" href="https://grpc.io/docs/guides/auth/#supported-auth-mechanisms">Mutual TLS (mTLS)</a></dt><dd><p>The client provides a certificate during connection establishment |
| which is verified by the server. The application does not need to |
| implement any authentication code, but must provision and distribute |
| certificates.</p> |
| <p>This may only be available in certain implementations, and is only |
| available when TLS is also enabled.</p> |
| </dd> |
| </dl> |
| <p>Some Flight implementations may expose the underlying gRPC API as |
| well, in which case any <a class="reference external" href="https://grpc.io/docs/guides/auth/">authentication method supported by gRPC</a> is available.</p> |
| </section> |
| <section id="location-uris"> |
| <span id="flight-location-uris"></span><h2>Location URIs<a class="headerlink" href="#location-uris" title="Link to this heading">#</a></h2> |
| <p>Flight is primarily defined in terms of its Protobuf and gRPC |
| specification below, but Arrow implementations may also support |
| alternative transports (see <a class="reference internal" href="../status.html#status-flight-rpc"><span class="std std-ref">Flight RPC</span></a>). Clients and |
| servers need to know which transport to use for a given URI in a |
| Location, so Flight implementations should use the following URI |
| schemes for the given transports:</p> |
| <div class="pst-scrollable-table-container"><table class="table"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Transport</p></th> |
| <th class="head"><p>URI Scheme</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>gRPC (plaintext)</p></td> |
| <td><p>grpc: or grpc+tcp:</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>gRPC (TLS)</p></td> |
| <td><p>grpc+tls:</p></td> |
| </tr> |
| <tr class="row-even"><td><p>gRPC (Unix domain socket)</p></td> |
| <td><p>grpc+unix:</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>(reuse connection)</p></td> |
| <td><p>arrow-flight-reuse-connection:</p></td> |
| </tr> |
| <tr class="row-even"><td><p>HTTP (1)</p></td> |
| <td><p>http: or https:</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <p>Notes:</p> |
| <ul class="simple"> |
| <li><dl class="simple"> |
| <dt>(1) See <a class="reference internal" href="#flight-extended-uris"><span class="std std-ref">Extended Location URIs</span></a> for semantics when using</dt><dd><p>http/https as the transport. It should be accessible via a GET request.</p> |
| </dd> |
| </dl> |
| </li> |
| </ul> |
| <section id="connection-reuse"> |
| <h3>Connection Reuse<a class="headerlink" href="#connection-reuse" title="Link to this heading">#</a></h3> |
| <p>“Reuse connection” above is not a particular transport. Instead, it |
| means that the client may try to execute DoGet against the same server |
| (and through the same connection) that it originally obtained the |
| FlightInfo from (i.e., that it called GetFlightInfo against). This is |
| interpreted the same way as when no specific <code class="docutils literal notranslate"><span class="pre">Location</span></code> are |
| returned.</p> |
| <p>This allows the server to return “itself” as one possible location to |
| fetch data without having to know its own public address, which can be |
| useful in deployments where knowing this would be difficult or |
| impossible. For example, a developer may forward a remote service in |
| a cloud environment to their local machine; in this case, the remote |
| service would have no way to know the local hostname and port that it |
| is being accessed over.</p> |
| <p>For compatibility reasons, the URI should always be |
| <code class="docutils literal notranslate"><span class="pre">arrow-flight-reuse-connection://?</span></code>, with the trailing empty query |
| string. Java’s URI implementation does not accept <code class="docutils literal notranslate"><span class="pre">scheme:</span></code> or |
| <code class="docutils literal notranslate"><span class="pre">scheme://</span></code>, and C++’s implementation does not accept an empty |
| string, so the obvious candidates are not compatible. The chosen |
| representation can be parsed by both implementations, as well as Go’s |
| <code class="docutils literal notranslate"><span class="pre">net/url</span></code> and Python’s <code class="docutils literal notranslate"><span class="pre">urllib.parse</span></code>.</p> |
| </section> |
| <section id="extended-location-uris"> |
| <span id="flight-extended-uris"></span><h3>Extended Location URIs<a class="headerlink" href="#extended-location-uris" title="Link to this heading">#</a></h3> |
| <p>In addition to alternative transports, a server may also return |
| URIs that reference an external service or object storage location. |
| This can be useful in cases where intermediate data is cached as |
| Apache Parquet files on cloud storage or is otherwise accessible |
| via an HTTP service. In these scenarios, it is more efficient to be |
| able to provide a URI where the client may simply download the data |
| directly, rather than requiring a Flight service to read it back into |
| memory and serve it from a <code class="docutils literal notranslate"><span class="pre">DoGet</span></code> request.</p> |
| <p>To avoid the complexities of Flight clients having to implement support |
| for multiple different cloud storage vendors (e.g. AWS S3, Google Cloud), |
| we extend the URIs to only allow an HTTP/HTTPS URI where the client can |
| perform a simple GET request to download the data. Authentication can be |
| handled either by negotiating externally to the Flight protocol or by the |
| server sending a presigned URL that the client can make a GET request to. |
| This should be supported by all current major cloud storage vendors, meaning |
| only the server needs to know the semantics of the underlying object store APIs.</p> |
| <p>When using an extended location URI, the client should ignore any |
| value in the <code class="docutils literal notranslate"><span class="pre">Ticket</span></code> field of the <code class="docutils literal notranslate"><span class="pre">FlightEndpoint</span></code>. The |
| <code class="docutils literal notranslate"><span class="pre">Ticket</span></code> is only used for identifying data in the context of a |
| Flight service, and is not needed when the client is directly |
| downloading data from an external service.</p> |
| <p>Clients should assume that, unless otherwise specified, the data is |
| being returned using the <a class="reference internal" href="Columnar.html#format-ipc"><span class="std std-ref">Serialization and Interprocess Communication (IPC)</span></a> just as it would |
| via a <code class="docutils literal notranslate"><span class="pre">DoGet</span></code> call. If the returned <code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> header is a generic |
| media type such as <code class="docutils literal notranslate"><span class="pre">application/octet-stream</span></code>, the client should still assume |
| it is an Arrow IPC stream. For other media types, such as Apache Parquet, |
| the server should use the appropriate IANA Media Type that a client |
| would recognize.</p> |
| <p>Finally, the server may also allow the client to choose what format the |
| data is returned in by respecting the <code class="docutils literal notranslate"><span class="pre">Accept</span></code> header in the request. |
| If multiple formats are requested and supported, the choice of which to |
| use is server-specific. If none of the requested content-types are |
| supported, the server may respond with either 406 (Not Acceptable), |
| 415 (Unsupported Media Type), or successfully respond with a different |
| format that it does support, along with the correct <code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> |
| header.</p> |
| </section> |
| </section> |
| <section id="error-handling"> |
| <h2>Error Handling<a class="headerlink" href="#error-handling" title="Link to this heading">#</a></h2> |
| <p>Arrow Flight defines its own set of error codes. The implementation |
| differs between languages (e.g. in C++, Unimplemented is a general |
| Arrow error status while it’s a Flight-specific exception in Java), |
| but the following set is exposed:</p> |
| <div class="pst-scrollable-table-container"><table class="table"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Error Code</p></th> |
| <th class="head"><p>Description</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>UNKNOWN</p></td> |
| <td><p>An unknown error. The default if no other |
| error applies.</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>INTERNAL</p></td> |
| <td><p>An error internal to the service |
| implementation occurred.</p></td> |
| </tr> |
| <tr class="row-even"><td><p>INVALID_ARGUMENT</p></td> |
| <td><p>The client passed an invalid argument to |
| the RPC.</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>TIMED_OUT</p></td> |
| <td><p>The operation exceeded a timeout or |
| deadline.</p></td> |
| </tr> |
| <tr class="row-even"><td><p>NOT_FOUND</p></td> |
| <td><p>The requested resource (action, data |
| stream) was not found.</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>ALREADY_EXISTS</p></td> |
| <td><p>The resource already exists.</p></td> |
| </tr> |
| <tr class="row-even"><td><p>CANCELLED</p></td> |
| <td><p>The operation was cancelled (either by the |
| client or the server).</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>UNAUTHENTICATED</p></td> |
| <td><p>The client is not authenticated.</p></td> |
| </tr> |
| <tr class="row-even"><td><p>UNAUTHORIZED</p></td> |
| <td><p>The client is authenticated, but does not |
| have permissions for the requested |
| operation.</p></td> |
| </tr> |
| <tr class="row-odd"><td><p>UNIMPLEMENTED</p></td> |
| <td><p>The RPC is not implemented.</p></td> |
| </tr> |
| <tr class="row-even"><td><p>UNAVAILABLE</p></td> |
| <td><p>The server is not available. May be emitted |
| by the client for connectivity reasons.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </section> |
| <section id="external-resources"> |
| <h2>External Resources<a class="headerlink" href="#external-resources" title="Link to this heading">#</a></h2> |
| <ul class="simple"> |
| <li><p><a class="reference external" href="https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/">https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/</a></p></li> |
| <li><p><a class="reference external" href="https://arrow.apache.org/blog/2018/10/09/0.11.0-release/">https://arrow.apache.org/blog/2018/10/09/0.11.0-release/</a></p></li> |
| <li><p><a class="reference external" href="https://www.slideshare.net/JacquesNadeau5/apache-arrow-flight-overview">https://www.slideshare.net/JacquesNadeau5/apache-arrow-flight-overview</a></p></li> |
| </ul> |
| </section> |
| <section id="protocol-buffer-definitions"> |
| <h2>Protocol Buffer Definitions<a class="headerlink" href="#protocol-buffer-definitions" title="Link to this heading">#</a></h2> |
| <div class="highlight-protobuf notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="cm">/*</span> |
| <span class="linenos"> 2</span><span class="cm"> * Licensed to the Apache Software Foundation (ASF) under one</span> |
| <span class="linenos"> 3</span><span class="cm"> * or more contributor license agreements. See the NOTICE file</span> |
| <span class="linenos"> 4</span><span class="cm"> * distributed with this work for additional information</span> |
| <span class="linenos"> 5</span><span class="cm"> * regarding copyright ownership. The ASF licenses this file</span> |
| <span class="linenos"> 6</span><span class="cm"> * to you under the Apache License, Version 2.0 (the</span> |
| <span class="linenos"> 7</span><span class="cm"> * "License"); you may not use this file except in compliance</span> |
| <span class="linenos"> 8</span><span class="cm"> * with the License. You may obtain a copy of the License at</span> |
| <span class="linenos"> 9</span><span class="cm"> * <p></span> |
| <span class="linenos"> 10</span><span class="cm"> * http://www.apache.org/licenses/LICENSE-2.0</span> |
| <span class="linenos"> 11</span><span class="cm"> * <p></span> |
| <span class="linenos"> 12</span><span class="cm"> * Unless required by applicable law or agreed to in writing, software</span> |
| <span class="linenos"> 13</span><span class="cm"> * distributed under the License is distributed on an "AS IS" BASIS,</span> |
| <span class="linenos"> 14</span><span class="cm"> * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span> |
| <span class="linenos"> 15</span><span class="cm"> * See the License for the specific language governing permissions and</span> |
| <span class="linenos"> 16</span><span class="cm"> * limitations under the License.</span> |
| <span class="linenos"> 17</span><span class="cm"> */</span> |
| <span class="linenos"> 18</span> |
| <span class="linenos"> 19</span><span class="k">syntax</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"proto3"</span><span class="p">;</span> |
| <span class="linenos"> 20</span><span class="k">import</span><span class="w"> </span><span class="s">"google/protobuf/timestamp.proto"</span><span class="p">;</span> |
| <span class="linenos"> 21</span> |
| <span class="linenos"> 22</span><span class="k">option</span><span class="w"> </span><span class="na">java_package</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"org.apache.arrow.flight.impl"</span><span class="p">;</span> |
| <span class="linenos"> 23</span><span class="k">option</span><span class="w"> </span><span class="na">go_package</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"github.com/apache/arrow-go/arrow/flight/gen/flight"</span><span class="p">;</span> |
| <span class="linenos"> 24</span><span class="k">option</span><span class="w"> </span><span class="na">csharp_namespace</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">"Apache.Arrow.Flight.Protocol"</span><span class="p">;</span> |
| <span class="linenos"> 25</span> |
| <span class="linenos"> 26</span><span class="kn">package</span><span class="w"> </span><span class="nn">arrow</span><span class="o">.</span><span class="n">flight.protocol</span><span class="p">;</span> |
| <span class="linenos"> 27</span> |
| <span class="linenos"> 28</span><span class="cm">/*</span> |
| <span class="linenos"> 29</span><span class="cm"> * A flight service is an endpoint for retrieving or storing Arrow data. A</span> |
| <span class="linenos"> 30</span><span class="cm"> * flight service can expose one or more predefined endpoints that can be</span> |
| <span class="linenos"> 31</span><span class="cm"> * accessed using the Arrow Flight Protocol. Additionally, a flight service</span> |
| <span class="linenos"> 32</span><span class="cm"> * can expose a set of actions that are available.</span> |
| <span class="linenos"> 33</span><span class="cm"> */</span> |
| <span class="linenos"> 34</span><span class="kd">service</span><span class="w"> </span><span class="n">FlightService</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos"> 35</span> |
| <span class="linenos"> 36</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos"> 37</span><span class="cm"> * Handshake between client and server. Depending on the server, the</span> |
| <span class="linenos"> 38</span><span class="cm"> * handshake may be required to determine the token that should be used for</span> |
| <span class="linenos"> 39</span><span class="cm"> * future operations. Both request and response are streams to allow multiple</span> |
| <span class="linenos"> 40</span><span class="cm"> * round-trips depending on auth mechanism.</span> |
| <span class="linenos"> 41</span><span class="cm"> */</span> |
| <span class="linenos"> 42</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">Handshake</span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">HandshakeRequest</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">HandshakeResponse</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos"> 43</span> |
| <span class="linenos"> 44</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos"> 45</span><span class="cm"> * Get a list of available streams given a particular criteria. Most flight</span> |
| <span class="linenos"> 46</span><span class="cm"> * services will expose one or more streams that are readily available for</span> |
| <span class="linenos"> 47</span><span class="cm"> * retrieval. This api allows listing the streams available for</span> |
| <span class="linenos"> 48</span><span class="cm"> * consumption. A user can also provide a criteria. The criteria can limit</span> |
| <span class="linenos"> 49</span><span class="cm"> * the subset of streams that can be listed via this interface. Each flight</span> |
| <span class="linenos"> 50</span><span class="cm"> * service allows its own definition of how to consume criteria.</span> |
| <span class="linenos"> 51</span><span class="cm"> */</span> |
| <span class="linenos"> 52</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">ListFlights</span><span class="p">(</span><span class="n">Criteria</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">FlightInfo</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos"> 53</span> |
| <span class="linenos"> 54</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos"> 55</span><span class="cm"> * For a given FlightDescriptor, get information about how the flight can be</span> |
| <span class="linenos"> 56</span><span class="cm"> * consumed. This is a useful interface if the consumer of the interface</span> |
| <span class="linenos"> 57</span><span class="cm"> * already can identify the specific flight to consume. This interface can</span> |
| <span class="linenos"> 58</span><span class="cm"> * also allow a consumer to generate a flight stream through a specified</span> |
| <span class="linenos"> 59</span><span class="cm"> * descriptor. For example, a flight descriptor might be something that</span> |
| <span class="linenos"> 60</span><span class="cm"> * includes a SQL statement or a Pickled Python operation that will be</span> |
| <span class="linenos"> 61</span><span class="cm"> * executed. In those cases, the descriptor will not be previously available</span> |
| <span class="linenos"> 62</span><span class="cm"> * within the list of available streams provided by ListFlights but will be</span> |
| <span class="linenos"> 63</span><span class="cm"> * available for consumption for the duration defined by the specific flight</span> |
| <span class="linenos"> 64</span><span class="cm"> * service.</span> |
| <span class="linenos"> 65</span><span class="cm"> */</span> |
| <span class="linenos"> 66</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">GetFlightInfo</span><span class="p">(</span><span class="n">FlightDescriptor</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">FlightInfo</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos"> 67</span> |
| <span class="linenos"> 68</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos"> 69</span><span class="cm"> * For a given FlightDescriptor, start a query and get information</span> |
| <span class="linenos"> 70</span><span class="cm"> * to poll its execution status. This is a useful interface if the</span> |
| <span class="linenos"> 71</span><span class="cm"> * query may be a long-running query. The first PollFlightInfo call</span> |
| <span class="linenos"> 72</span><span class="cm"> * should return as quickly as possible. (GetFlightInfo doesn't</span> |
| <span class="linenos"> 73</span><span class="cm"> * return until the query is complete.)</span> |
| <span class="linenos"> 74</span><span class="cm"> *</span> |
| <span class="linenos"> 75</span><span class="cm"> * A client can consume any available results before</span> |
| <span class="linenos"> 76</span><span class="cm"> * the query is completed. See PollInfo.info for details.</span> |
| <span class="linenos"> 77</span><span class="cm"> *</span> |
| <span class="linenos"> 78</span><span class="cm"> * A client can poll the updated query status by calling</span> |
| <span class="linenos"> 79</span><span class="cm"> * PollFlightInfo() with PollInfo.flight_descriptor. A server</span> |
| <span class="linenos"> 80</span><span class="cm"> * should not respond until the result would be different from last</span> |
| <span class="linenos"> 81</span><span class="cm"> * time. That way, the client can "long poll" for updates</span> |
| <span class="linenos"> 82</span><span class="cm"> * without constantly making requests. Clients can set a short timeout</span> |
| <span class="linenos"> 83</span><span class="cm"> * to avoid blocking calls if desired.</span> |
| <span class="linenos"> 84</span><span class="cm"> *</span> |
| <span class="linenos"> 85</span><span class="cm"> * A client can't use PollInfo.flight_descriptor after</span> |
| <span class="linenos"> 86</span><span class="cm"> * PollInfo.expiration_time passes. A server might not accept the</span> |
| <span class="linenos"> 87</span><span class="cm"> * retry descriptor anymore and the query may be cancelled.</span> |
| <span class="linenos"> 88</span><span class="cm"> *</span> |
| <span class="linenos"> 89</span><span class="cm"> * A client may use the CancelFlightInfo action with</span> |
| <span class="linenos"> 90</span><span class="cm"> * PollInfo.info to cancel the running query.</span> |
| <span class="linenos"> 91</span><span class="cm"> */</span> |
| <span class="linenos"> 92</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">PollFlightInfo</span><span class="p">(</span><span class="n">FlightDescriptor</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">PollInfo</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos"> 93</span> |
| <span class="linenos"> 94</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos"> 95</span><span class="cm"> * For a given FlightDescriptor, get the Schema as described in Schema.fbs::Schema</span> |
| <span class="linenos"> 96</span><span class="cm"> * This is used when a consumer needs the Schema of flight stream. Similar to</span> |
| <span class="linenos"> 97</span><span class="cm"> * GetFlightInfo this interface may generate a new flight that was not previously</span> |
| <span class="linenos"> 98</span><span class="cm"> * available in ListFlights.</span> |
| <span class="linenos"> 99</span><span class="cm"> */</span> |
| <span class="linenos">100</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">GetSchema</span><span class="p">(</span><span class="n">FlightDescriptor</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">SchemaResult</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">101</span> |
| <span class="linenos">102</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">103</span><span class="cm"> * Retrieve a single stream associated with a particular descriptor</span> |
| <span class="linenos">104</span><span class="cm"> * associated with the referenced ticket. A Flight can be composed of one or</span> |
| <span class="linenos">105</span><span class="cm"> * more streams where each stream can be retrieved using a separate opaque</span> |
| <span class="linenos">106</span><span class="cm"> * ticket that the flight service uses for managing a collection of streams.</span> |
| <span class="linenos">107</span><span class="cm"> */</span> |
| <span class="linenos">108</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">DoGet</span><span class="p">(</span><span class="n">Ticket</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">FlightData</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">109</span> |
| <span class="linenos">110</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">111</span><span class="cm"> * Push a stream to the flight service associated with a particular</span> |
| <span class="linenos">112</span><span class="cm"> * flight stream. This allows a client of a flight service to upload a stream</span> |
| <span class="linenos">113</span><span class="cm"> * of data. Depending on the particular flight service, a client consumer</span> |
| <span class="linenos">114</span><span class="cm"> * could be allowed to upload a single stream per descriptor or an unlimited</span> |
| <span class="linenos">115</span><span class="cm"> * number. In the latter, the service might implement a 'seal' action that</span> |
| <span class="linenos">116</span><span class="cm"> * can be applied to a descriptor once all streams are uploaded.</span> |
| <span class="linenos">117</span><span class="cm"> */</span> |
| <span class="linenos">118</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">DoPut</span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">FlightData</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">PutResult</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">119</span> |
| <span class="linenos">120</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">121</span><span class="cm"> * Open a bidirectional data channel for a given descriptor. This</span> |
| <span class="linenos">122</span><span class="cm"> * allows clients to send and receive arbitrary Arrow data and</span> |
| <span class="linenos">123</span><span class="cm"> * application-specific metadata in a single logical stream. In</span> |
| <span class="linenos">124</span><span class="cm"> * contrast to DoGet/DoPut, this is more suited for clients</span> |
| <span class="linenos">125</span><span class="cm"> * offloading computation (rather than storage) to a Flight service.</span> |
| <span class="linenos">126</span><span class="cm"> */</span> |
| <span class="linenos">127</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">DoExchange</span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">FlightData</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">FlightData</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">128</span> |
| <span class="linenos">129</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">130</span><span class="cm"> * Flight services can support an arbitrary number of simple actions in</span> |
| <span class="linenos">131</span><span class="cm"> * addition to the possible ListFlights, GetFlightInfo, DoGet, DoPut</span> |
| <span class="linenos">132</span><span class="cm"> * operations that are potentially available. DoAction allows a flight client</span> |
| <span class="linenos">133</span><span class="cm"> * to do a specific action against a flight service. An action includes</span> |
| <span class="linenos">134</span><span class="cm"> * opaque request and response objects that are specific to the type action</span> |
| <span class="linenos">135</span><span class="cm"> * being undertaken.</span> |
| <span class="linenos">136</span><span class="cm"> */</span> |
| <span class="linenos">137</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">DoAction</span><span class="p">(</span><span class="n">Action</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">Result</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">138</span> |
| <span class="linenos">139</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">140</span><span class="cm"> * A flight service exposes all of the available action types that it has</span> |
| <span class="linenos">141</span><span class="cm"> * along with descriptions. This allows different flight consumers to</span> |
| <span class="linenos">142</span><span class="cm"> * understand the capabilities of the flight service.</span> |
| <span class="linenos">143</span><span class="cm"> */</span> |
| <span class="linenos">144</span><span class="w"> </span><span class="k">rpc</span><span class="w"> </span><span class="n">ListActions</span><span class="p">(</span><span class="n">Empty</span><span class="p">)</span><span class="w"> </span><span class="k">returns</span><span class="w"> </span><span class="p">(</span><span class="n">stream</span><span class="w"> </span><span class="n">ActionType</span><span class="p">)</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">145</span><span class="p">}</span> |
| <span class="linenos">146</span> |
| <span class="linenos">147</span><span class="cm">/*</span> |
| <span class="linenos">148</span><span class="cm"> * The request that a client provides to a server on handshake.</span> |
| <span class="linenos">149</span><span class="cm"> */</span> |
| <span class="linenos">150</span><span class="kd">message</span><span class="w"> </span><span class="nc">HandshakeRequest</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">151</span> |
| <span class="linenos">152</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">153</span><span class="cm"> * A defined protocol version</span> |
| <span class="linenos">154</span><span class="cm"> */</span> |
| <span class="linenos">155</span><span class="w"> </span><span class="kt">uint64</span><span class="w"> </span><span class="na">protocol_version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">156</span> |
| <span class="linenos">157</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">158</span><span class="cm"> * Arbitrary auth/handshake info.</span> |
| <span class="linenos">159</span><span class="cm"> */</span> |
| <span class="linenos">160</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">payload</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">161</span><span class="p">}</span> |
| <span class="linenos">162</span> |
| <span class="linenos">163</span><span class="kd">message</span><span class="w"> </span><span class="nc">HandshakeResponse</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">164</span> |
| <span class="linenos">165</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">166</span><span class="cm"> * A defined protocol version</span> |
| <span class="linenos">167</span><span class="cm"> */</span> |
| <span class="linenos">168</span><span class="w"> </span><span class="kt">uint64</span><span class="w"> </span><span class="na">protocol_version</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">169</span> |
| <span class="linenos">170</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">171</span><span class="cm"> * Arbitrary auth/handshake info.</span> |
| <span class="linenos">172</span><span class="cm"> */</span> |
| <span class="linenos">173</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">payload</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">174</span><span class="p">}</span> |
| <span class="linenos">175</span> |
| <span class="linenos">176</span><span class="cm">/*</span> |
| <span class="linenos">177</span><span class="cm"> * A message for doing simple auth.</span> |
| <span class="linenos">178</span><span class="cm"> */</span> |
| <span class="linenos">179</span><span class="kd">message</span><span class="w"> </span><span class="nc">BasicAuth</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">180</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">username</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">181</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">password</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">182</span><span class="p">}</span> |
| <span class="linenos">183</span> |
| <span class="linenos">184</span><span class="kd">message</span><span class="w"> </span><span class="nc">Empty</span><span class="w"> </span><span class="p">{}</span> |
| <span class="linenos">185</span> |
| <span class="linenos">186</span><span class="cm">/*</span> |
| <span class="linenos">187</span><span class="cm"> * Describes an available action, including both the name used for execution</span> |
| <span class="linenos">188</span><span class="cm"> * along with a short description of the purpose of the action.</span> |
| <span class="linenos">189</span><span class="cm"> */</span> |
| <span class="linenos">190</span><span class="kd">message</span><span class="w"> </span><span class="nc">ActionType</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">191</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">192</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">description</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">193</span><span class="p">}</span> |
| <span class="linenos">194</span> |
| <span class="linenos">195</span><span class="cm">/*</span> |
| <span class="linenos">196</span><span class="cm"> * A service specific expression that can be used to return a limited set</span> |
| <span class="linenos">197</span><span class="cm"> * of available Arrow Flight streams.</span> |
| <span class="linenos">198</span><span class="cm"> */</span> |
| <span class="linenos">199</span><span class="kd">message</span><span class="w"> </span><span class="nc">Criteria</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">200</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">expression</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">201</span><span class="p">}</span> |
| <span class="linenos">202</span> |
| <span class="linenos">203</span><span class="cm">/*</span> |
| <span class="linenos">204</span><span class="cm"> * An opaque action specific for the service.</span> |
| <span class="linenos">205</span><span class="cm"> */</span> |
| <span class="linenos">206</span><span class="kd">message</span><span class="w"> </span><span class="nc">Action</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">207</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">208</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">body</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">209</span><span class="p">}</span> |
| <span class="linenos">210</span> |
| <span class="linenos">211</span><span class="cm">/*</span> |
| <span class="linenos">212</span><span class="cm"> * An opaque result returned after executing an action.</span> |
| <span class="linenos">213</span><span class="cm"> */</span> |
| <span class="linenos">214</span><span class="kd">message</span><span class="w"> </span><span class="nc">Result</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">215</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">body</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">216</span><span class="p">}</span> |
| <span class="linenos">217</span> |
| <span class="linenos">218</span><span class="cm">/*</span> |
| <span class="linenos">219</span><span class="cm"> * Wrap the result of a getSchema call</span> |
| <span class="linenos">220</span><span class="cm"> */</span> |
| <span class="linenos">221</span><span class="kd">message</span><span class="w"> </span><span class="nc">SchemaResult</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">222</span><span class="w"> </span><span class="c1">// The schema of the dataset in its IPC form:</span> |
| <span class="linenos">223</span><span class="w"> </span><span class="c1">// 4 bytes - an optional IPC_CONTINUATION_TOKEN prefix</span> |
| <span class="linenos">224</span><span class="w"> </span><span class="c1">// 4 bytes - the byte length of the payload</span> |
| <span class="linenos">225</span><span class="w"> </span><span class="c1">// a flatbuffer Message whose header is the Schema</span> |
| <span class="linenos">226</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">schema</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">227</span><span class="p">}</span> |
| <span class="linenos">228</span> |
| <span class="linenos">229</span><span class="cm">/*</span> |
| <span class="linenos">230</span><span class="cm"> * The name or tag for a Flight. May be used as a way to retrieve or generate</span> |
| <span class="linenos">231</span><span class="cm"> * a flight or be used to expose a set of previously defined flights.</span> |
| <span class="linenos">232</span><span class="cm"> */</span> |
| <span class="linenos">233</span><span class="kd">message</span><span class="w"> </span><span class="nc">FlightDescriptor</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">234</span> |
| <span class="linenos">235</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">236</span><span class="cm"> * Describes what type of descriptor is defined.</span> |
| <span class="linenos">237</span><span class="cm"> */</span> |
| <span class="linenos">238</span><span class="w"> </span><span class="kd">enum</span><span class="w"> </span><span class="n">DescriptorType</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">239</span> |
| <span class="linenos">240</span><span class="w"> </span><span class="c1">// Protobuf pattern, not used.</span> |
| <span class="linenos">241</span><span class="w"> </span><span class="na">UNKNOWN</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span> |
| <span class="linenos">242</span> |
| <span class="linenos">243</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">244</span><span class="cm"> * A named path that identifies a dataset. A path is composed of a string</span> |
| <span class="linenos">245</span><span class="cm"> * or list of strings describing a particular dataset. This is conceptually</span> |
| <span class="linenos">246</span><span class="cm"> * similar to a path inside a filesystem.</span> |
| <span class="linenos">247</span><span class="cm"> */</span> |
| <span class="linenos">248</span><span class="w"> </span><span class="na">PATH</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">249</span> |
| <span class="linenos">250</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">251</span><span class="cm"> * An opaque command to generate a dataset.</span> |
| <span class="linenos">252</span><span class="cm"> */</span> |
| <span class="linenos">253</span><span class="w"> </span><span class="na">CMD</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">254</span><span class="w"> </span><span class="p">}</span> |
| <span class="linenos">255</span> |
| <span class="linenos">256</span><span class="w"> </span><span class="n">DescriptorType</span><span class="w"> </span><span class="na">type</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">257</span> |
| <span class="linenos">258</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">259</span><span class="cm"> * Opaque value used to express a command. Should only be defined when</span> |
| <span class="linenos">260</span><span class="cm"> * type = CMD.</span> |
| <span class="linenos">261</span><span class="cm"> */</span> |
| <span class="linenos">262</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">cmd</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">263</span> |
| <span class="linenos">264</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">265</span><span class="cm"> * List of strings identifying a particular dataset. Should only be defined</span> |
| <span class="linenos">266</span><span class="cm"> * when type = PATH.</span> |
| <span class="linenos">267</span><span class="cm"> */</span> |
| <span class="linenos">268</span><span class="w"> </span><span class="k">repeated</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">path</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">269</span><span class="p">}</span> |
| <span class="linenos">270</span> |
| <span class="linenos">271</span><span class="cm">/*</span> |
| <span class="linenos">272</span><span class="cm"> * The access coordinates for retrieval of a dataset. With a FlightInfo, a</span> |
| <span class="linenos">273</span><span class="cm"> * consumer is able to determine how to retrieve a dataset.</span> |
| <span class="linenos">274</span><span class="cm"> */</span> |
| <span class="linenos">275</span><span class="kd">message</span><span class="w"> </span><span class="nc">FlightInfo</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">276</span><span class="w"> </span><span class="c1">// The schema of the dataset in its IPC form:</span> |
| <span class="linenos">277</span><span class="w"> </span><span class="c1">// 4 bytes - an optional IPC_CONTINUATION_TOKEN prefix</span> |
| <span class="linenos">278</span><span class="w"> </span><span class="c1">// 4 bytes - the byte length of the payload</span> |
| <span class="linenos">279</span><span class="w"> </span><span class="c1">// a flatbuffer Message whose header is the Schema</span> |
| <span class="linenos">280</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">schema</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">281</span> |
| <span class="linenos">282</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">283</span><span class="cm"> * The descriptor associated with this info.</span> |
| <span class="linenos">284</span><span class="cm"> */</span> |
| <span class="linenos">285</span><span class="w"> </span><span class="n">FlightDescriptor</span><span class="w"> </span><span class="na">flight_descriptor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">286</span> |
| <span class="linenos">287</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">288</span><span class="cm"> * A list of endpoints associated with the flight. To consume the</span> |
| <span class="linenos">289</span><span class="cm"> * whole flight, all endpoints (and hence all Tickets) must be</span> |
| <span class="linenos">290</span><span class="cm"> * consumed. Endpoints can be consumed in any order.</span> |
| <span class="linenos">291</span><span class="cm"> *</span> |
| <span class="linenos">292</span><span class="cm"> * In other words, an application can use multiple endpoints to</span> |
| <span class="linenos">293</span><span class="cm"> * represent partitioned data.</span> |
| <span class="linenos">294</span><span class="cm"> *</span> |
| <span class="linenos">295</span><span class="cm"> * If the returned data has an ordering, an application can use</span> |
| <span class="linenos">296</span><span class="cm"> * "FlightInfo.ordered = true" or should return the all data in a</span> |
| <span class="linenos">297</span><span class="cm"> * single endpoint. Otherwise, there is no ordering defined on</span> |
| <span class="linenos">298</span><span class="cm"> * endpoints or the data within.</span> |
| <span class="linenos">299</span><span class="cm"> *</span> |
| <span class="linenos">300</span><span class="cm"> * A client can read ordered data by reading data from returned</span> |
| <span class="linenos">301</span><span class="cm"> * endpoints, in order, from front to back.</span> |
| <span class="linenos">302</span><span class="cm"> *</span> |
| <span class="linenos">303</span><span class="cm"> * Note that a client may ignore "FlightInfo.ordered = true". If an</span> |
| <span class="linenos">304</span><span class="cm"> * ordering is important for an application, an application must</span> |
| <span class="linenos">305</span><span class="cm"> * choose one of them:</span> |
| <span class="linenos">306</span><span class="cm"> *</span> |
| <span class="linenos">307</span><span class="cm"> * * An application requires that all clients must read data in</span> |
| <span class="linenos">308</span><span class="cm"> * returned endpoints order.</span> |
| <span class="linenos">309</span><span class="cm"> * * An application must return the all data in a single endpoint.</span> |
| <span class="linenos">310</span><span class="cm"> */</span> |
| <span class="linenos">311</span><span class="w"> </span><span class="k">repeated</span><span class="w"> </span><span class="n">FlightEndpoint</span><span class="w"> </span><span class="na">endpoint</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">312</span> |
| <span class="linenos">313</span><span class="w"> </span><span class="c1">// Set these to -1 if unknown.</span> |
| <span class="linenos">314</span><span class="w"> </span><span class="kt">int64</span><span class="w"> </span><span class="na">total_records</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span> |
| <span class="linenos">315</span><span class="w"> </span><span class="kt">int64</span><span class="w"> </span><span class="na">total_bytes</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">5</span><span class="p">;</span> |
| <span class="linenos">316</span> |
| <span class="linenos">317</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">318</span><span class="cm"> * FlightEndpoints are in the same order as the data.</span> |
| <span class="linenos">319</span><span class="cm"> */</span> |
| <span class="linenos">320</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="na">ordered</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">6</span><span class="p">;</span> |
| <span class="linenos">321</span> |
| <span class="linenos">322</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">323</span><span class="cm"> * Application-defined metadata.</span> |
| <span class="linenos">324</span><span class="cm"> *</span> |
| <span class="linenos">325</span><span class="cm"> * There is no inherent or required relationship between this</span> |
| <span class="linenos">326</span><span class="cm"> * and the app_metadata fields in the FlightEndpoints or resulting</span> |
| <span class="linenos">327</span><span class="cm"> * FlightData messages. Since this metadata is application-defined,</span> |
| <span class="linenos">328</span><span class="cm"> * a given application could define there to be a relationship,</span> |
| <span class="linenos">329</span><span class="cm"> * but there is none required by the spec.</span> |
| <span class="linenos">330</span><span class="cm"> */</span> |
| <span class="linenos">331</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">app_metadata</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">7</span><span class="p">;</span> |
| <span class="linenos">332</span><span class="p">}</span> |
| <span class="linenos">333</span> |
| <span class="linenos">334</span><span class="cm">/*</span> |
| <span class="linenos">335</span><span class="cm"> * The information to process a long-running query.</span> |
| <span class="linenos">336</span><span class="cm"> */</span> |
| <span class="linenos">337</span><span class="kd">message</span><span class="w"> </span><span class="nc">PollInfo</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">338</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">339</span><span class="cm"> * The currently available results.</span> |
| <span class="linenos">340</span><span class="cm"> *</span> |
| <span class="linenos">341</span><span class="cm"> * If "flight_descriptor" is not specified, the query is complete</span> |
| <span class="linenos">342</span><span class="cm"> * and "info" specifies all results. Otherwise, "info" contains</span> |
| <span class="linenos">343</span><span class="cm"> * partial query results.</span> |
| <span class="linenos">344</span><span class="cm"> *</span> |
| <span class="linenos">345</span><span class="cm"> * Note that each PollInfo response contains a complete</span> |
| <span class="linenos">346</span><span class="cm"> * FlightInfo (not just the delta between the previous and current</span> |
| <span class="linenos">347</span><span class="cm"> * FlightInfo).</span> |
| <span class="linenos">348</span><span class="cm"> *</span> |
| <span class="linenos">349</span><span class="cm"> * Subsequent PollInfo responses may only append new endpoints to</span> |
| <span class="linenos">350</span><span class="cm"> * info.</span> |
| <span class="linenos">351</span><span class="cm"> *</span> |
| <span class="linenos">352</span><span class="cm"> * Clients can begin fetching results via DoGet(Ticket) with the</span> |
| <span class="linenos">353</span><span class="cm"> * ticket in the info before the query is</span> |
| <span class="linenos">354</span><span class="cm"> * completed. FlightInfo.ordered is also valid.</span> |
| <span class="linenos">355</span><span class="cm"> */</span> |
| <span class="linenos">356</span><span class="w"> </span><span class="n">FlightInfo</span><span class="w"> </span><span class="na">info</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">357</span> |
| <span class="linenos">358</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">359</span><span class="cm"> * The descriptor the client should use on the next try.</span> |
| <span class="linenos">360</span><span class="cm"> * If unset, the query is complete.</span> |
| <span class="linenos">361</span><span class="cm"> */</span> |
| <span class="linenos">362</span><span class="w"> </span><span class="n">FlightDescriptor</span><span class="w"> </span><span class="na">flight_descriptor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">363</span> |
| <span class="linenos">364</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">365</span><span class="cm"> * Query progress. If known, must be in [0.0, 1.0] but need not be</span> |
| <span class="linenos">366</span><span class="cm"> * monotonic or nondecreasing. If unknown, do not set.</span> |
| <span class="linenos">367</span><span class="cm"> */</span> |
| <span class="linenos">368</span><span class="w"> </span><span class="k">optional</span><span class="w"> </span><span class="kt">double</span><span class="w"> </span><span class="na">progress</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">369</span> |
| <span class="linenos">370</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">371</span><span class="cm"> * Expiration time for this request. After this passes, the server</span> |
| <span class="linenos">372</span><span class="cm"> * might not accept the retry descriptor anymore (and the query may</span> |
| <span class="linenos">373</span><span class="cm"> * be cancelled). This may be updated on a call to PollFlightInfo.</span> |
| <span class="linenos">374</span><span class="cm"> */</span> |
| <span class="linenos">375</span><span class="w"> </span><span class="n">google.protobuf.Timestamp</span><span class="w"> </span><span class="na">expiration_time</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span> |
| <span class="linenos">376</span><span class="p">}</span> |
| <span class="linenos">377</span> |
| <span class="linenos">378</span><span class="cm">/*</span> |
| <span class="linenos">379</span><span class="cm"> * The request of the CancelFlightInfo action.</span> |
| <span class="linenos">380</span><span class="cm"> *</span> |
| <span class="linenos">381</span><span class="cm"> * The request should be stored in Action.body.</span> |
| <span class="linenos">382</span><span class="cm"> */</span> |
| <span class="linenos">383</span><span class="kd">message</span><span class="w"> </span><span class="nc">CancelFlightInfoRequest</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">384</span><span class="w"> </span><span class="n">FlightInfo</span><span class="w"> </span><span class="na">info</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">385</span><span class="p">}</span> |
| <span class="linenos">386</span> |
| <span class="linenos">387</span><span class="cm">/*</span> |
| <span class="linenos">388</span><span class="cm"> * The result of a cancel operation.</span> |
| <span class="linenos">389</span><span class="cm"> *</span> |
| <span class="linenos">390</span><span class="cm"> * This is used by CancelFlightInfoResult.status.</span> |
| <span class="linenos">391</span><span class="cm"> */</span> |
| <span class="linenos">392</span><span class="kd">enum</span><span class="w"> </span><span class="n">CancelStatus</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">393</span><span class="w"> </span><span class="c1">// The cancellation status is unknown. Servers should avoid using</span> |
| <span class="linenos">394</span><span class="w"> </span><span class="c1">// this value (send a NOT_FOUND error if the requested query is</span> |
| <span class="linenos">395</span><span class="w"> </span><span class="c1">// not known). Clients can retry the request.</span> |
| <span class="linenos">396</span><span class="w"> </span><span class="na">CANCEL_STATUS_UNSPECIFIED</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span> |
| <span class="linenos">397</span><span class="w"> </span><span class="c1">// The cancellation request is complete. Subsequent requests with</span> |
| <span class="linenos">398</span><span class="w"> </span><span class="c1">// the same payload may return CANCELLED or a NOT_FOUND error.</span> |
| <span class="linenos">399</span><span class="w"> </span><span class="na">CANCEL_STATUS_CANCELLED</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">400</span><span class="w"> </span><span class="c1">// The cancellation request is in progress. The client may retry</span> |
| <span class="linenos">401</span><span class="w"> </span><span class="c1">// the cancellation request.</span> |
| <span class="linenos">402</span><span class="w"> </span><span class="na">CANCEL_STATUS_CANCELLING</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">403</span><span class="w"> </span><span class="c1">// The query is not cancellable. The client should not retry the</span> |
| <span class="linenos">404</span><span class="w"> </span><span class="c1">// cancellation request.</span> |
| <span class="linenos">405</span><span class="w"> </span><span class="na">CANCEL_STATUS_NOT_CANCELLABLE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">406</span><span class="p">}</span> |
| <span class="linenos">407</span> |
| <span class="linenos">408</span><span class="cm">/*</span> |
| <span class="linenos">409</span><span class="cm"> * The result of the CancelFlightInfo action.</span> |
| <span class="linenos">410</span><span class="cm"> *</span> |
| <span class="linenos">411</span><span class="cm"> * The result should be stored in Result.body.</span> |
| <span class="linenos">412</span><span class="cm"> */</span> |
| <span class="linenos">413</span><span class="kd">message</span><span class="w"> </span><span class="nc">CancelFlightInfoResult</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">414</span><span class="w"> </span><span class="n">CancelStatus</span><span class="w"> </span><span class="na">status</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">415</span><span class="p">}</span> |
| <span class="linenos">416</span> |
| <span class="linenos">417</span><span class="cm">/*</span> |
| <span class="linenos">418</span><span class="cm"> * An opaque identifier that the service can use to retrieve a particular</span> |
| <span class="linenos">419</span><span class="cm"> * portion of a stream.</span> |
| <span class="linenos">420</span><span class="cm"> *</span> |
| <span class="linenos">421</span><span class="cm"> * Tickets are meant to be single use. It is an error/application-defined</span> |
| <span class="linenos">422</span><span class="cm"> * behavior to reuse a ticket.</span> |
| <span class="linenos">423</span><span class="cm"> */</span> |
| <span class="linenos">424</span><span class="kd">message</span><span class="w"> </span><span class="nc">Ticket</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">425</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">ticket</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">426</span><span class="p">}</span> |
| <span class="linenos">427</span> |
| <span class="linenos">428</span><span class="cm">/*</span> |
| <span class="linenos">429</span><span class="cm"> * A location to retrieve a particular stream from. This URI should be one of</span> |
| <span class="linenos">430</span><span class="cm"> * the following:</span> |
| <span class="linenos">431</span><span class="cm"> * - An empty string or the string 'arrow-flight-reuse-connection://?':</span> |
| <span class="linenos">432</span><span class="cm"> * indicating that the ticket can be redeemed on the service where the</span> |
| <span class="linenos">433</span><span class="cm"> * ticket was generated via a DoGet request.</span> |
| <span class="linenos">434</span><span class="cm"> * - A valid grpc URI (grpc://, grpc+tls://, grpc+unix://, etc.):</span> |
| <span class="linenos">435</span><span class="cm"> * indicating that the ticket can be redeemed on the service at the given</span> |
| <span class="linenos">436</span><span class="cm"> * URI via a DoGet request.</span> |
| <span class="linenos">437</span><span class="cm"> * - A valid HTTP URI (http://, https://, etc.):</span> |
| <span class="linenos">438</span><span class="cm"> * indicating that the client should perform a GET request against the</span> |
| <span class="linenos">439</span><span class="cm"> * given URI to retrieve the stream. The ticket should be empty</span> |
| <span class="linenos">440</span><span class="cm"> * in this case and should be ignored by the client. Cloud object storage</span> |
| <span class="linenos">441</span><span class="cm"> * can be utilized by presigned URLs or mediating the auth separately and</span> |
| <span class="linenos">442</span><span class="cm"> * returning the full URL (e.g. https://amzn-s3-demo-bucket.s3.us-west-2.amazonaws.com/...).</span> |
| <span class="linenos">443</span><span class="cm"> *</span> |
| <span class="linenos">444</span><span class="cm"> * We allow non-Flight URIs for the purpose of allowing Flight services to indicate that</span> |
| <span class="linenos">445</span><span class="cm"> * results can be downloaded in formats other than Arrow (such as Parquet) or to allow</span> |
| <span class="linenos">446</span><span class="cm"> * direct fetching of results from a URI to reduce excess copying and data movement.</span> |
| <span class="linenos">447</span><span class="cm"> * In these cases, the following conventions should be followed by servers and clients:</span> |
| <span class="linenos">448</span><span class="cm"> *</span> |
| <span class="linenos">449</span><span class="cm"> * - Unless otherwise specified by the 'Content-Type' header of the response,</span> |
| <span class="linenos">450</span><span class="cm"> * a client should assume the response is using the Arrow IPC Streaming format.</span> |
| <span class="linenos">451</span><span class="cm"> * Usage of an IANA media type like 'application/octet-stream' should be assumed to</span> |
| <span class="linenos">452</span><span class="cm"> * be using the Arrow IPC Streaming format.</span> |
| <span class="linenos">453</span><span class="cm"> * - The server may allow the client to choose a specific response format by</span> |
| <span class="linenos">454</span><span class="cm"> * specifying an 'Accept' header in the request, such as 'application/vnd.apache.parquet'</span> |
| <span class="linenos">455</span><span class="cm"> * or 'application/vnd.apache.arrow.stream'. If multiple types are requested and</span> |
| <span class="linenos">456</span><span class="cm"> * supported by the server, the choice of which to use is server-specific. If</span> |
| <span class="linenos">457</span><span class="cm"> * none of the requested content-types are supported, the server may respond with</span> |
| <span class="linenos">458</span><span class="cm"> * either 406 (Not Acceptable) or 415 (Unsupported Media Type), or successfully</span> |
| <span class="linenos">459</span><span class="cm"> * respond with a different format that it does support along with the correct</span> |
| <span class="linenos">460</span><span class="cm"> * 'Content-Type' header.</span> |
| <span class="linenos">461</span><span class="cm"> *</span> |
| <span class="linenos">462</span><span class="cm"> * Note: new schemes may be proposed in the future to allow for more flexibility based</span> |
| <span class="linenos">463</span><span class="cm"> * on community requests.</span> |
| <span class="linenos">464</span><span class="cm"> */</span> |
| <span class="linenos">465</span><span class="kd">message</span><span class="w"> </span><span class="nc">Location</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">466</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">uri</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">467</span><span class="p">}</span> |
| <span class="linenos">468</span> |
| <span class="linenos">469</span><span class="cm">/*</span> |
| <span class="linenos">470</span><span class="cm"> * A particular stream or split associated with a flight.</span> |
| <span class="linenos">471</span><span class="cm"> */</span> |
| <span class="linenos">472</span><span class="kd">message</span><span class="w"> </span><span class="nc">FlightEndpoint</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">473</span> |
| <span class="linenos">474</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">475</span><span class="cm"> * Token used to retrieve this stream.</span> |
| <span class="linenos">476</span><span class="cm"> */</span> |
| <span class="linenos">477</span><span class="w"> </span><span class="n">Ticket</span><span class="w"> </span><span class="na">ticket</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">478</span> |
| <span class="linenos">479</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">480</span><span class="cm"> * A list of URIs where this ticket can be redeemed via DoGet().</span> |
| <span class="linenos">481</span><span class="cm"> *</span> |
| <span class="linenos">482</span><span class="cm"> * If the list is empty, the expectation is that the ticket can only</span> |
| <span class="linenos">483</span><span class="cm"> * be redeemed on the current service where the ticket was</span> |
| <span class="linenos">484</span><span class="cm"> * generated.</span> |
| <span class="linenos">485</span><span class="cm"> *</span> |
| <span class="linenos">486</span><span class="cm"> * If the list is not empty, the expectation is that the ticket can be</span> |
| <span class="linenos">487</span><span class="cm"> * redeemed at any of the locations, and that the data returned will be</span> |
| <span class="linenos">488</span><span class="cm"> * equivalent. In this case, the ticket may only be redeemed at one of the</span> |
| <span class="linenos">489</span><span class="cm"> * given locations, and not (necessarily) on the current service. If one</span> |
| <span class="linenos">490</span><span class="cm"> * of the given locations is "arrow-flight-reuse-connection://?", the</span> |
| <span class="linenos">491</span><span class="cm"> * client may redeem the ticket on the service where the ticket was</span> |
| <span class="linenos">492</span><span class="cm"> * generated (i.e., the same as above), in addition to the other</span> |
| <span class="linenos">493</span><span class="cm"> * locations. (This URI was chosen to maximize compatibility, as 'scheme:'</span> |
| <span class="linenos">494</span><span class="cm"> * or 'scheme://' are not accepted by Java's java.net.URI.)</span> |
| <span class="linenos">495</span><span class="cm"> *</span> |
| <span class="linenos">496</span><span class="cm"> * In other words, an application can use multiple locations to</span> |
| <span class="linenos">497</span><span class="cm"> * represent redundant and/or load balanced services.</span> |
| <span class="linenos">498</span><span class="cm"> */</span> |
| <span class="linenos">499</span><span class="w"> </span><span class="k">repeated</span><span class="w"> </span><span class="n">Location</span><span class="w"> </span><span class="na">location</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">500</span> |
| <span class="linenos">501</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">502</span><span class="cm"> * Expiration time of this stream. If present, clients may assume</span> |
| <span class="linenos">503</span><span class="cm"> * they can retry DoGet requests. Otherwise, it is</span> |
| <span class="linenos">504</span><span class="cm"> * application-defined whether DoGet requests may be retried.</span> |
| <span class="linenos">505</span><span class="cm"> */</span> |
| <span class="linenos">506</span><span class="w"> </span><span class="n">google.protobuf.Timestamp</span><span class="w"> </span><span class="na">expiration_time</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">507</span> |
| <span class="linenos">508</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">509</span><span class="cm"> * Application-defined metadata.</span> |
| <span class="linenos">510</span><span class="cm"> *</span> |
| <span class="linenos">511</span><span class="cm"> * There is no inherent or required relationship between this</span> |
| <span class="linenos">512</span><span class="cm"> * and the app_metadata fields in the FlightInfo or resulting</span> |
| <span class="linenos">513</span><span class="cm"> * FlightData messages. Since this metadata is application-defined,</span> |
| <span class="linenos">514</span><span class="cm"> * a given application could define there to be a relationship,</span> |
| <span class="linenos">515</span><span class="cm"> * but there is none required by the spec.</span> |
| <span class="linenos">516</span><span class="cm"> */</span> |
| <span class="linenos">517</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">app_metadata</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span> |
| <span class="linenos">518</span><span class="p">}</span> |
| <span class="linenos">519</span> |
| <span class="linenos">520</span><span class="cm">/*</span> |
| <span class="linenos">521</span><span class="cm"> * The request of the RenewFlightEndpoint action.</span> |
| <span class="linenos">522</span><span class="cm"> *</span> |
| <span class="linenos">523</span><span class="cm"> * The request should be stored in Action.body.</span> |
| <span class="linenos">524</span><span class="cm"> */</span> |
| <span class="linenos">525</span><span class="kd">message</span><span class="w"> </span><span class="nc">RenewFlightEndpointRequest</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">526</span><span class="w"> </span><span class="n">FlightEndpoint</span><span class="w"> </span><span class="na">endpoint</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">527</span><span class="p">}</span> |
| <span class="linenos">528</span> |
| <span class="linenos">529</span><span class="cm">/*</span> |
| <span class="linenos">530</span><span class="cm"> * A batch of Arrow data as part of a stream of batches.</span> |
| <span class="linenos">531</span><span class="cm"> */</span> |
| <span class="linenos">532</span><span class="kd">message</span><span class="w"> </span><span class="nc">FlightData</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">533</span> |
| <span class="linenos">534</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">535</span><span class="cm"> * The descriptor of the data. This is only relevant when a client is</span> |
| <span class="linenos">536</span><span class="cm"> * starting a new DoPut stream.</span> |
| <span class="linenos">537</span><span class="cm"> */</span> |
| <span class="linenos">538</span><span class="w"> </span><span class="n">FlightDescriptor</span><span class="w"> </span><span class="na">flight_descriptor</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">539</span> |
| <span class="linenos">540</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">541</span><span class="cm"> * Header for message data as described in Message.fbs::Message.</span> |
| <span class="linenos">542</span><span class="cm"> */</span> |
| <span class="linenos">543</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">data_header</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">544</span> |
| <span class="linenos">545</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">546</span><span class="cm"> * Application-defined metadata.</span> |
| <span class="linenos">547</span><span class="cm"> */</span> |
| <span class="linenos">548</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">app_metadata</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">549</span> |
| <span class="linenos">550</span><span class="w"> </span><span class="cm">/*</span> |
| <span class="linenos">551</span><span class="cm"> * The actual batch of Arrow data. Preferably handled with minimal-copies</span> |
| <span class="linenos">552</span><span class="cm"> * coming last in the definition to help with sidecar patterns (it is</span> |
| <span class="linenos">553</span><span class="cm"> * expected that some implementations will fetch this field off the wire</span> |
| <span class="linenos">554</span><span class="cm"> * with specialized code to avoid extra memory copies).</span> |
| <span class="linenos">555</span><span class="cm"> */</span> |
| <span class="linenos">556</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">data_body</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1000</span><span class="p">;</span> |
| <span class="linenos">557</span><span class="p">}</span> |
| <span class="linenos">558</span> |
| <span class="linenos">559</span><span class="cm">/**</span> |
| <span class="linenos">560</span><span class="cm"> * The response message associated with the submission of a DoPut.</span> |
| <span class="linenos">561</span><span class="cm"> */</span> |
| <span class="linenos">562</span><span class="kd">message</span><span class="w"> </span><span class="nc">PutResult</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">563</span><span class="w"> </span><span class="kt">bytes</span><span class="w"> </span><span class="na">app_metadata</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">564</span><span class="p">}</span> |
| <span class="linenos">565</span> |
| <span class="linenos">566</span><span class="cm">/*</span> |
| <span class="linenos">567</span><span class="cm"> * EXPERIMENTAL: Union of possible value types for a Session Option to be set to.</span> |
| <span class="linenos">568</span><span class="cm"> *</span> |
| <span class="linenos">569</span><span class="cm"> * By convention, an attempt to set a valueless SessionOptionValue should</span> |
| <span class="linenos">570</span><span class="cm"> * attempt to unset or clear the named option value on the server.</span> |
| <span class="linenos">571</span><span class="cm"> */</span> |
| <span class="linenos">572</span><span class="kd">message</span><span class="w"> </span><span class="nc">SessionOptionValue</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">573</span><span class="w"> </span><span class="kd">message</span><span class="w"> </span><span class="nc">StringListValue</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">574</span><span class="w"> </span><span class="k">repeated</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">values</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">575</span><span class="w"> </span><span class="p">}</span> |
| <span class="linenos">576</span> |
| <span class="linenos">577</span><span class="w"> </span><span class="k">oneof</span><span class="w"> </span><span class="n">option_value</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">578</span><span class="w"> </span><span class="kt">string</span><span class="w"> </span><span class="na">string_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">579</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="na">bool_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">580</span><span class="w"> </span><span class="kt">sfixed64</span><span class="w"> </span><span class="na">int64_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">581</span><span class="w"> </span><span class="kt">double</span><span class="w"> </span><span class="na">double_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">4</span><span class="p">;</span> |
| <span class="linenos">582</span><span class="w"> </span><span class="n">StringListValue</span><span class="w"> </span><span class="na">string_list_value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">5</span><span class="p">;</span> |
| <span class="linenos">583</span><span class="w"> </span><span class="p">}</span> |
| <span class="linenos">584</span><span class="p">}</span> |
| <span class="linenos">585</span> |
| <span class="linenos">586</span><span class="cm">/*</span> |
| <span class="linenos">587</span><span class="cm"> * EXPERIMENTAL: A request to set session options for an existing or new (implicit)</span> |
| <span class="linenos">588</span><span class="cm"> * server session.</span> |
| <span class="linenos">589</span><span class="cm"> *</span> |
| <span class="linenos">590</span><span class="cm"> * Sessions are persisted and referenced via a transport-level state management, typically</span> |
| <span class="linenos">591</span><span class="cm"> * RFC 6265 HTTP cookies when using an HTTP transport. The suggested cookie name or state</span> |
| <span class="linenos">592</span><span class="cm"> * context key is 'arrow_flight_session_id', although implementations may freely choose their</span> |
| <span class="linenos">593</span><span class="cm"> * own name.</span> |
| <span class="linenos">594</span><span class="cm"> *</span> |
| <span class="linenos">595</span><span class="cm"> * Session creation (if one does not already exist) is implied by this RPC request, however</span> |
| <span class="linenos">596</span><span class="cm"> * server implementations may choose to initiate a session that also contains client-provided</span> |
| <span class="linenos">597</span><span class="cm"> * session options at any other time, e.g. on authentication, or when any other call is made</span> |
| <span class="linenos">598</span><span class="cm"> * and the server wishes to use a session to persist any state (or lack thereof).</span> |
| <span class="linenos">599</span><span class="cm"> */</span> |
| <span class="linenos">600</span><span class="kd">message</span><span class="w"> </span><span class="nc">SetSessionOptionsRequest</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">601</span><span class="w"> </span><span class="n">map</span><span class="p"><</span><span class="kt">string</span><span class="p">,</span><span class="w"> </span><span class="n">SessionOptionValue</span><span class="p">></span><span class="w"> </span><span class="na">session_options</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">602</span><span class="p">}</span> |
| <span class="linenos">603</span> |
| <span class="linenos">604</span><span class="cm">/*</span> |
| <span class="linenos">605</span><span class="cm"> * EXPERIMENTAL: The results (individually) of setting a set of session options.</span> |
| <span class="linenos">606</span><span class="cm"> *</span> |
| <span class="linenos">607</span><span class="cm"> * Option names should only be present in the response if they were not successfully</span> |
| <span class="linenos">608</span><span class="cm"> * set on the server; that is, a response without an Error for a name provided in the</span> |
| <span class="linenos">609</span><span class="cm"> * SetSessionOptionsRequest implies that the named option value was set successfully.</span> |
| <span class="linenos">610</span><span class="cm"> */</span> |
| <span class="linenos">611</span><span class="kd">message</span><span class="w"> </span><span class="nc">SetSessionOptionsResult</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">612</span><span class="w"> </span><span class="kd">enum</span><span class="w"> </span><span class="n">ErrorValue</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">613</span><span class="w"> </span><span class="c1">// Protobuf deserialization fallback value: The status is unknown or unrecognized.</span> |
| <span class="linenos">614</span><span class="w"> </span><span class="c1">// Servers should avoid using this value. The request may be retried by the client.</span> |
| <span class="linenos">615</span><span class="w"> </span><span class="na">UNSPECIFIED</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span> |
| <span class="linenos">616</span><span class="w"> </span><span class="c1">// The given session option name is invalid.</span> |
| <span class="linenos">617</span><span class="w"> </span><span class="na">INVALID_NAME</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">618</span><span class="w"> </span><span class="c1">// The session option value or type is invalid.</span> |
| <span class="linenos">619</span><span class="w"> </span><span class="na">INVALID_VALUE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">620</span><span class="w"> </span><span class="c1">// The session option cannot be set.</span> |
| <span class="linenos">621</span><span class="w"> </span><span class="na">ERROR</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">622</span><span class="w"> </span><span class="p">}</span> |
| <span class="linenos">623</span> |
| <span class="linenos">624</span><span class="w"> </span><span class="kd">message</span><span class="w"> </span><span class="nc">Error</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">625</span><span class="w"> </span><span class="n">ErrorValue</span><span class="w"> </span><span class="na">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">626</span><span class="w"> </span><span class="p">}</span> |
| <span class="linenos">627</span> |
| <span class="linenos">628</span><span class="w"> </span><span class="n">map</span><span class="p"><</span><span class="kt">string</span><span class="p">,</span><span class="w"> </span><span class="n">Error</span><span class="p">></span><span class="w"> </span><span class="na">errors</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">629</span><span class="p">}</span> |
| <span class="linenos">630</span> |
| <span class="linenos">631</span><span class="cm">/*</span> |
| <span class="linenos">632</span><span class="cm"> * EXPERIMENTAL: A request to access the session options for the current server session.</span> |
| <span class="linenos">633</span><span class="cm"> *</span> |
| <span class="linenos">634</span><span class="cm"> * The existing session is referenced via a cookie header or similar (see</span> |
| <span class="linenos">635</span><span class="cm"> * SetSessionOptionsRequest above); it is an error to make this request with a missing,</span> |
| <span class="linenos">636</span><span class="cm"> * invalid, or expired session cookie header or other implementation-defined session</span> |
| <span class="linenos">637</span><span class="cm"> * reference token.</span> |
| <span class="linenos">638</span><span class="cm"> */</span> |
| <span class="linenos">639</span><span class="kd">message</span><span class="w"> </span><span class="nc">GetSessionOptionsRequest</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">640</span><span class="p">}</span> |
| <span class="linenos">641</span> |
| <span class="linenos">642</span><span class="cm">/*</span> |
| <span class="linenos">643</span><span class="cm"> * EXPERIMENTAL: The result containing the current server session options.</span> |
| <span class="linenos">644</span><span class="cm"> */</span> |
| <span class="linenos">645</span><span class="kd">message</span><span class="w"> </span><span class="nc">GetSessionOptionsResult</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">646</span><span class="w"> </span><span class="n">map</span><span class="p"><</span><span class="kt">string</span><span class="p">,</span><span class="w"> </span><span class="n">SessionOptionValue</span><span class="p">></span><span class="w"> </span><span class="na">session_options</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">647</span><span class="p">}</span> |
| <span class="linenos">648</span> |
| <span class="linenos">649</span><span class="cm">/*</span> |
| <span class="linenos">650</span><span class="cm"> * Request message for the "Close Session" action.</span> |
| <span class="linenos">651</span><span class="cm"> *</span> |
| <span class="linenos">652</span><span class="cm"> * The exiting session is referenced via a cookie header.</span> |
| <span class="linenos">653</span><span class="cm"> */</span> |
| <span class="linenos">654</span><span class="kd">message</span><span class="w"> </span><span class="nc">CloseSessionRequest</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">655</span><span class="p">}</span> |
| <span class="linenos">656</span> |
| <span class="linenos">657</span><span class="cm">/*</span> |
| <span class="linenos">658</span><span class="cm"> * The result of closing a session.</span> |
| <span class="linenos">659</span><span class="cm"> */</span> |
| <span class="linenos">660</span><span class="kd">message</span><span class="w"> </span><span class="nc">CloseSessionResult</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">661</span><span class="w"> </span><span class="kd">enum</span><span class="w"> </span><span class="n">Status</span><span class="w"> </span><span class="p">{</span> |
| <span class="linenos">662</span><span class="w"> </span><span class="c1">// Protobuf deserialization fallback value: The session close status is unknown or</span> |
| <span class="linenos">663</span><span class="w"> </span><span class="c1">// not recognized. Servers should avoid using this value (send a NOT_FOUND error if</span> |
| <span class="linenos">664</span><span class="w"> </span><span class="c1">// the requested session is not known or expired). Clients can retry the request.</span> |
| <span class="linenos">665</span><span class="w"> </span><span class="na">UNSPECIFIED</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span> |
| <span class="linenos">666</span><span class="w"> </span><span class="c1">// The session close request is complete. Subsequent requests with</span> |
| <span class="linenos">667</span><span class="w"> </span><span class="c1">// the same session produce a NOT_FOUND error.</span> |
| <span class="linenos">668</span><span class="w"> </span><span class="na">CLOSED</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">669</span><span class="w"> </span><span class="c1">// The session close request is in progress. The client may retry</span> |
| <span class="linenos">670</span><span class="w"> </span><span class="c1">// the close request.</span> |
| <span class="linenos">671</span><span class="w"> </span><span class="na">CLOSING</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="p">;</span> |
| <span class="linenos">672</span><span class="w"> </span><span class="c1">// The session is not closeable. The client should not retry the</span> |
| <span class="linenos">673</span><span class="w"> </span><span class="c1">// close request.</span> |
| <span class="linenos">674</span><span class="w"> </span><span class="na">NOT_CLOSEABLE</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="p">;</span> |
| <span class="linenos">675</span><span class="w"> </span><span class="p">}</span> |
| <span class="linenos">676</span> |
| <span class="linenos">677</span><span class="w"> </span><span class="n">Status</span><span class="w"> </span><span class="na">status</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| <span class="linenos">678</span><span class="p">}</span> |
| </pre></div> |
| </div> |
| </section> |
| </section> |
| |
| |
| </article> |
| |
| |
| |
| |
| |
| <footer class="prev-next-footer d-print-none"> |
| |
| <div class="prev-next-area"> |
| <a class="left-prev" |
| href="DissociatedIPC.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">Dissociated IPC Protocol</p> |
| </div> |
| </a> |
| <a class="right-next" |
| href="FlightSql.html" |
| title="next page"> |
| <div class="prev-next-info"> |
| <p class="prev-next-subtitle">next</p> |
| <p class="prev-next-title">Arrow Flight SQL</p> |
| </div> |
| <i class="fa-solid fa-angle-right"></i> |
| </a> |
| </div> |
| </footer> |
| |
| </div> |
| |
| |
| |
| <dialog id="pst-secondary-sidebar-modal"></dialog> |
| <div id="pst-secondary-sidebar" 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="#rpc-methods-and-request-patterns">RPC Methods and Request Patterns</a><ul class="visible nav section-nav flex-column"> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#downloading-data">Downloading Data</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#downloading-data-by-running-a-heavy-query">Downloading Data by Running a Heavy Query</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#uploading-data">Uploading Data</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#exchanging-data">Exchanging Data</a></li> |
| </ul> |
| </li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#authentication">Authentication</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#location-uris">Location URIs</a><ul class="visible nav section-nav flex-column"> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#connection-reuse">Connection Reuse</a></li> |
| <li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#extended-location-uris">Extended Location URIs</a></li> |
| </ul> |
| </li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#error-handling">Error Handling</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#external-resources">External Resources</a></li> |
| <li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#protocol-buffer-definitions">Protocol Buffer Definitions</a></li> |
| </ul> |
| </nav></div> |
| |
| <div class="sidebar-secondary-item"> |
| |
| |
| <div class="tocsection editthispage"> |
| <a href="https://github.com/apache/arrow/edit/main/docs/source/format/Flight.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 defer src="../_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf"></script> |
| <script defer src="../_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></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-2025 Apache Software Foundation. |
| Apache Arrow, Arrow, Apache, the Apache 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> 8.2.3. |
| <br/> |
| </p> |
| </div> |
| |
| </div> |
| |
| |
| |
| <div class="footer-items__end"> |
| |
| <div class="footer-item"> |
| <p class="theme-version"> |
| <!-- # L10n: Setting the PST URL as an argument as this does not need to be localized --> |
| Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.16.1. |
| </p></div> |
| |
| </div> |
| |
| </div> |
| |
| </footer> |
| </body> |
| </html> |
