<!doctype html>
<html lang="zh-CN" data-theme="light">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <meta name="generator" content="VuePress 2.0.0-beta.66" />
    <meta name="theme" content="VuePress Theme Hope" />
    <link rel="alternate" hreflang="en-us" href="https://iotdb.apache.org/UserGuide/Master/API/Programming-Python-Native-API.html"><meta property="og:url" content="https://iotdb.apache.org/zh/UserGuide/Master/API/Programming-Python-Native-API.html"><meta property="og:site_name" content="IoTDB Website"><meta property="og:title" content="Python 原生接口"><meta property="og:description" content="依赖 在使用 Python 原生接口包前，您需要安装 thrift (>=0.13) 依赖。 如何使用 （示例） 首先下载包：pip3 install apache-iotdb 您可以从这里得到一个使用该包进行数据读写的例子：Session Example (https://github.com/apache/iotdb/blob/master/cli..."><meta property="og:type" content="article"><meta property="og:locale" content="zh-CN"><meta property="og:locale:alternate" content="en-US"><meta property="og:updated_time" content="2023-09-04T12:41:20.000Z"><meta property="article:modified_time" content="2023-09-04T12:41:20.000Z"><script type="application/ld+json">{"@context":"https://schema.org","@type":"Article","headline":"Python 原生接口","image":[""],"dateModified":"2023-09-04T12:41:20.000Z","author":[]}</script><link rel="icon" href="/favicon.ico"><meta name="Description" content="Apache IoTDB: Time Series Database for IoT"><meta name="Keywords" content="TSDB, time series, time series database, IoTDB, IoT database, IoT data management,时序数据库, 时间序列管理, IoTDB, 物联网数据库, 实时数据库, 物联网数据管理, 物联网数据"><meta name="baidu-site-verification" content="wfKETzB3OT"><meta name="google-site-verification" content="mZWAoRY0yj_HAr-s47zHCGHzx5Ju-RVm5wDbPnwQYFo"><title>Python 原生接口 | IoTDB Website</title><meta name="description" content="依赖 在使用 Python 原生接口包前，您需要安装 thrift (>=0.13) 依赖。 如何使用 （示例） 首先下载包：pip3 install apache-iotdb 您可以从这里得到一个使用该包进行数据读写的例子：Session Example (https://github.com/apache/iotdb/blob/master/cli...">
    <style>
      :root {
        --bg-color: #fff;
      }

      html[data-theme="dark"] {
        --bg-color: #1d1e1f;
      }

      html,
      body {
        background: var(--bg-color);
      }
    </style>
    <script>
      const userMode = localStorage.getItem("vuepress-theme-hope-scheme");
      const systemDarkMode =
        window.matchMedia &&
        window.matchMedia("(prefers-color-scheme: dark)").matches;

      if (userMode === "dark" || (userMode !== "light" && systemDarkMode)) {
        document.documentElement.setAttribute("data-theme", "dark");
      }
    </script>
    <link rel="preload" href="/assets/style-35dc1830.css" as="style"><link rel="stylesheet" href="/assets/style-35dc1830.css">
    <link rel="modulepreload" href="/assets/app-601a6ddd.js"><link rel="modulepreload" href="/assets/Programming-Python-Native-API.html-c8d8ffb7.js"><link rel="modulepreload" href="/assets/Programming-Python-Native-API.html-7d1053fb.js">
  </head>
  <body>
    <div id="app"><!--[--><!--[--><!--[--><span tabindex="-1"></span><a href="#main-content" class="vp-skip-link sr-only">跳至主要內容</a><!--]--><!--[--><div class="theme-container no-sidebar has-toc"><!--[--><header id="navbar" class="vp-navbar hide-icon"><div class="vp-navbar-start"><button type="button" class="vp-toggle-sidebar-button" title="Toggle Sidebar"><span class="icon"></span></button><!--[--><!----><!--]--><!--[--><a class="vp-link vp-brand" href="/zh/"><img class="vp-nav-logo" src="/logo.png" alt="IoTDB Website"><!----><span class="vp-site-name hide-in-pad">IoTDB Website</span></a><!--]--><!--[--><!----><!--]--></div><div class="vp-navbar-center"><!--[--><!----><!--]--><!--[--><!--]--><!--[--><!----><!--]--></div><div class="vp-navbar-end"><!--[--><!----><!--]--><!--[--><div id="docsearch-container"></div><nav class="vp-nav-links"><div class="nav-item hide-in-mobile"><div class="dropdown-wrapper"><button type="button" class="dropdown-title" aria-label="文档"><span class="title"><!---->文档</span><span class="arrow"></span><ul class="nav-dropdown"><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/UserGuide/V1.1.x/QuickStart/QuickStart.html"><!---->v1.1.x<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/UserGuide/V1.0.x/QuickStart/QuickStart.html"><!---->v1.0.x<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/UserGuide/V0.13.x/QuickStart/QuickStart.html"><!---->v0.13.x<!----></a></li></ul></button></div></div><div class="nav-item hide-in-mobile"><a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=177051872" rel="noopener noreferrer" target="_blank" aria-label="系统设计" class="nav-link"><!---->系统设计<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></div><div class="nav-item hide-in-mobile"><a class="vp-link nav-link" href="/zh/Download/"><!---->下载<!----></a></div><div class="nav-item hide-in-mobile"><div class="dropdown-wrapper"><button type="button" class="dropdown-title" aria-label="社区"><span class="title"><!---->社区</span><span class="arrow"></span><ul class="nav-dropdown"><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Community/About.html"><!---->关于社区<!----></a></li><li class="dropdown-item"><a href="https://cwiki.apache.org/confluence/display/iotdb" rel="noopener noreferrer" target="_blank" aria-label="Wiki" class="nav-link"><!---->Wiki<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Community/Community-Project-Committers.html"><!---->开发人员<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Community/Community-Powered-By.html"><!---->技术支持<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/Community/Materials.html"><!---->活动与报告<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Community/Feedback.html"><!---->交流与反馈<!----></a></li></ul></button></div></div><div class="nav-item hide-in-mobile"><div class="dropdown-wrapper"><button type="button" class="dropdown-title" aria-label="开发"><span class="title"><!---->开发</span><span class="arrow"></span><ul class="nav-dropdown"><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/VoteRelease.html"><!---->如何投票<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/HowToCommit.html"><!---->如何提交代码<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/HowToJoin.html"><!---->成为Contributor<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/Committer.html"><!---->成为Committer<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/ContributeGuide.html"><!---->项目开发指南<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/HowtoContributeCode.html"><!---->技术贡献指南<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/format-changelist.html"><!---->TsFile的更改列表<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link" href="/zh/Development/rpc-changelist.html"><!---->RPC变更清单<!----></a></li></ul></button></div></div><div class="nav-item hide-in-mobile"><div class="dropdown-wrapper"><button type="button" class="dropdown-title" aria-label="ASF"><span class="title"><!---->ASF</span><span class="arrow"></span><ul class="nav-dropdown"><li class="dropdown-item"><a href="https://www.apache.org/" rel="noopener noreferrer" target="_blank" aria-label="基金会" class="nav-link"><!---->基金会<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li><li class="dropdown-item"><a href="https://www.apache.org/licenses/" rel="noopener noreferrer" target="_blank" aria-label="许可证" class="nav-link"><!---->许可证<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li><li class="dropdown-item"><a href="https://www.apache.org/security/" rel="noopener noreferrer" target="_blank" aria-label="安全" class="nav-link"><!---->安全<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li><li class="dropdown-item"><a href="https://www.apache.org/foundation/sponsorship.html" rel="noopener noreferrer" target="_blank" aria-label="赞助" class="nav-link"><!---->赞助<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li><li class="dropdown-item"><a href="https://www.apache.org/foundation/thanks.html" rel="noopener noreferrer" target="_blank" aria-label="致谢" class="nav-link"><!---->致谢<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li><li class="dropdown-item"><a href="https://www.apache.org/events/current-event" rel="noopener noreferrer" target="_blank" aria-label="活动" class="nav-link"><!---->活动<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></li></ul></button></div></div></nav><div class="nav-item"><div class="dropdown-wrapper i18n-dropdown"><button type="button" class="dropdown-title" aria-label="选择语言"><!--[--><svg xmlns="http://www.w3.org/2000/svg" class="icon i18n-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="i18n icon" style="width:1rem;height:1rem;vertical-align:middle;"><path d="M379.392 460.8 494.08 575.488l-42.496 102.4L307.2 532.48 138.24 701.44l-71.68-72.704L234.496 460.8l-45.056-45.056c-27.136-27.136-51.2-66.56-66.56-108.544h112.64c7.68 14.336 16.896 27.136 26.112 35.84l45.568 46.08 45.056-45.056C382.976 312.32 409.6 247.808 409.6 204.8H0V102.4h256V0h102.4v102.4h256v102.4H512c0 70.144-37.888 161.28-87.04 210.944L378.88 460.8zM576 870.4 512 1024H409.6l256-614.4H768l256 614.4H921.6l-64-153.6H576zM618.496 768h196.608L716.8 532.48 618.496 768z"></path></svg><!--]--><span class="arrow"></span><ul class="nav-dropdown"><li class="dropdown-item"><a class="vp-link nav-link" href="/UserGuide/Master/API/Programming-Python-Native-API.html"><!---->English<!----></a></li><li class="dropdown-item"><a class="vp-link nav-link active" href="/zh/UserGuide/Master/API/Programming-Python-Native-API.html"><!---->简体中文<!----></a></li></ul></button></div></div><div class="nav-item hide-in-mobile"><button type="button" id="appearance-switch"><svg xmlns="http://www.w3.org/2000/svg" class="icon auto-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="auto icon" style="display:block;"><path d="M512 992C246.92 992 32 777.08 32 512S246.92 32 512 32s480 214.92 480 480-214.92 480-480 480zm0-840c-198.78 0-360 161.22-360 360 0 198.84 161.22 360 360 360s360-161.16 360-360c0-198.78-161.22-360-360-360zm0 660V212c165.72 0 300 134.34 300 300 0 165.72-134.28 300-300 300z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="dark icon" style="display:none;"><path d="M524.8 938.667h-4.267a439.893 439.893 0 0 1-313.173-134.4 446.293 446.293 0 0 1-11.093-597.334A432.213 432.213 0 0 1 366.933 90.027a42.667 42.667 0 0 1 45.227 9.386 42.667 42.667 0 0 1 10.24 42.667 358.4 358.4 0 0 0 82.773 375.893 361.387 361.387 0 0 0 376.747 82.774 42.667 42.667 0 0 1 54.187 55.04 433.493 433.493 0 0 1-99.84 154.88 438.613 438.613 0 0 1-311.467 128z"></path></svg><svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="light icon" style="display:none;"><path d="M952 552h-80a40 40 0 0 1 0-80h80a40 40 0 0 1 0 80zM801.88 280.08a41 41 0 0 1-57.96-57.96l57.96-58a41.04 41.04 0 0 1 58 58l-58 57.96zM512 752a240 240 0 1 1 0-480 240 240 0 0 1 0 480zm0-560a40 40 0 0 1-40-40V72a40 40 0 0 1 80 0v80a40 40 0 0 1-40 40zm-289.88 88.08-58-57.96a41.04 41.04 0 0 1 58-58l57.96 58a41 41 0 0 1-57.96 57.96zM192 512a40 40 0 0 1-40 40H72a40 40 0 0 1 0-80h80a40 40 0 0 1 40 40zm30.12 231.92a41 41 0 0 1 57.96 57.96l-57.96 58a41.04 41.04 0 0 1-58-58l58-57.96zM512 832a40 40 0 0 1 40 40v80a40 40 0 0 1-80 0v-80a40 40 0 0 1 40-40zm289.88-88.08 58 57.96a41.04 41.04 0 0 1-58 58l-57.96-58a41 41 0 0 1 57.96-57.96z"></path></svg></button></div><div class="nav-item vp-repo"><a class="vp-repo-link" href="https://github.com/apache/iotdb" target="_blank" rel="noopener noreferrer" aria-label="GitHub"><svg xmlns="http://www.w3.org/2000/svg" class="icon github-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="github icon" style="width:1.25rem;height:1.25rem;vertical-align:middle;"><path d="M511.957 21.333C241.024 21.333 21.333 240.981 21.333 512c0 216.832 140.544 400.725 335.574 465.664 24.49 4.395 32.256-10.07 32.256-23.083 0-11.69.256-44.245 0-85.205-136.448 29.61-164.736-64.64-164.736-64.64-22.315-56.704-54.4-71.765-54.4-71.765-44.587-30.464 3.285-29.824 3.285-29.824 49.195 3.413 75.179 50.517 75.179 50.517 43.776 75.008 114.816 53.333 142.762 40.79 4.523-31.66 17.152-53.377 31.19-65.537-108.971-12.458-223.488-54.485-223.488-242.602 0-53.547 19.114-97.323 50.517-131.67-5.035-12.33-21.93-62.293 4.779-129.834 0 0 41.258-13.184 134.912 50.346a469.803 469.803 0 0 1 122.88-16.554c41.642.213 83.626 5.632 122.88 16.554 93.653-63.488 134.784-50.346 134.784-50.346 26.752 67.541 9.898 117.504 4.864 129.834 31.402 34.347 50.474 78.123 50.474 131.67 0 188.586-114.73 230.016-224.042 242.09 17.578 15.232 33.578 44.672 33.578 90.454v135.85c0 13.142 7.936 27.606 32.854 22.87C862.25 912.597 1002.667 728.747 1002.667 512c0-271.019-219.648-490.667-490.71-490.667z"></path></svg></a></div><!--]--><!--[--><!----><!--]--><button type="button" class="vp-toggle-navbar-button" aria-label="Toggle Navbar" aria-expanded="false" aria-controls="nav-screen"><span><span class="vp-top"></span><span class="vp-middle"></span><span class="vp-bottom"></span></span></button></div></header><!----><!--]--><!----><div class="toggle-sidebar-wrapper"><span class="arrow start"></span></div><aside id="sidebar" class="vp-sidebar"><!--[--><!----><!--]--><ul class="vp-sidebar-links"></ul><!--[--><!----><!--]--></aside><!--[--><main id="main-content" class="vp-page"><!--[--><!----><!----><nav class="vp-breadcrumb disable"></nav><div class="vp-page-title"><h1><!---->Python 原生接口</h1><div class="page-info"><!----><!----><span class="page-date-info" aria-label="写作日期"><svg xmlns="http://www.w3.org/2000/svg" class="icon calendar-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="calendar icon"><path d="M716.4 110.137c0-18.753-14.72-33.473-33.472-33.473-18.753 0-33.473 14.72-33.473 33.473v33.473h66.993v-33.473zm-334.87 0c0-18.753-14.72-33.473-33.473-33.473s-33.52 14.72-33.52 33.473v33.473h66.993v-33.473zm468.81 33.52H716.4v100.465c0 18.753-14.72 33.473-33.472 33.473a33.145 33.145 0 01-33.473-33.473V143.657H381.53v100.465c0 18.753-14.72 33.473-33.473 33.473a33.145 33.145 0 01-33.473-33.473V143.657H180.6A134.314 134.314 0 0046.66 277.595v535.756A134.314 134.314 0 00180.6 947.289h669.74a134.36 134.36 0 00133.94-133.938V277.595a134.314 134.314 0 00-133.94-133.938zm33.473 267.877H147.126a33.145 33.145 0 01-33.473-33.473c0-18.752 14.72-33.473 33.473-33.473h736.687c18.752 0 33.472 14.72 33.472 33.473a33.145 33.145 0 01-33.472 33.473z"></path></svg><span><!----></span><meta property="datePublished" content="2023-09-04T12:41:20.000Z"></span><!----><span class="page-reading-time-info" aria-label="阅读时间"><svg xmlns="http://www.w3.org/2000/svg" class="icon timer-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="timer icon"><path d="M799.387 122.15c4.402-2.978 7.38-7.897 7.38-13.463v-1.165c0-8.933-7.38-16.312-16.312-16.312H256.33c-8.933 0-16.311 7.38-16.311 16.312v1.165c0 5.825 2.977 10.874 7.637 13.592 4.143 194.44 97.22 354.963 220.201 392.763-122.204 37.542-214.893 196.511-220.2 389.397-4.661 5.049-7.638 11.651-7.638 19.03v5.825h566.49v-5.825c0-7.379-2.849-13.981-7.509-18.9-5.049-193.016-97.867-351.985-220.2-389.527 123.24-37.67 216.446-198.453 220.588-392.892zM531.16 450.445v352.632c117.674 1.553 211.787 40.778 211.787 88.676H304.097c0-48.286 95.149-87.382 213.728-88.676V450.445c-93.077-3.107-167.901-81.297-167.901-177.093 0-8.803 6.99-15.793 15.793-15.793 8.803 0 15.794 6.99 15.794 15.793 0 80.261 63.69 145.635 142.01 145.635s142.011-65.374 142.011-145.635c0-8.803 6.99-15.793 15.794-15.793s15.793 6.99 15.793 15.793c0 95.019-73.789 172.82-165.96 177.093z"></path></svg><span>大约 11 分钟</span><meta property="timeRequired" content="PT11M"></span><!----><!----></div><hr></div><div class="toc-place-holder"><aside id="toc"><!--[--><!----><!--]--><div class="toc-header">此页内容<button type="button" class="print-button" title="打印"><svg xmlns="http://www.w3.org/2000/svg" class="icon print-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="print icon"><path d="M819.2 364.8h-44.8V128c0-17.067-14.933-32-32-32H281.6c-17.067 0-32 14.933-32 32v236.8h-44.8C145.067 364.8 96 413.867 96 473.6v192c0 59.733 49.067 108.8 108.8 108.8h44.8V896c0 17.067 14.933 32 32 32h460.8c17.067 0 32-14.933 32-32V774.4h44.8c59.733 0 108.8-49.067 108.8-108.8v-192c0-59.733-49.067-108.8-108.8-108.8zM313.6 160h396.8v204.8H313.6V160zm396.8 704H313.6V620.8h396.8V864zM864 665.6c0 25.6-19.2 44.8-44.8 44.8h-44.8V588.8c0-17.067-14.933-32-32-32H281.6c-17.067 0-32 14.933-32 32v121.6h-44.8c-25.6 0-44.8-19.2-44.8-44.8v-192c0-25.6 19.2-44.8 44.8-44.8h614.4c25.6 0 44.8 19.2 44.8 44.8v192z"></path></svg></button></div><div class="toc-wrapper"><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#依赖">依赖</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#如何使用-示例">如何使用 （示例）</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#基本接口说明">基本接口说明</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#初始化">初始化</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#通过sessionpool管理session连接">通过SessionPool管理session连接</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#数据定义接口-ddl">数据定义接口 DDL</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#database-管理">Database 管理</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#时间序列管理">时间序列管理</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#数据操作接口-dml">数据操作接口 DML</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#数据写入">数据写入</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#带有类型推断的写入">带有类型推断的写入</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#对齐时间序列的写入">对齐时间序列的写入</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#iotdb-sql-接口">IoTDB-SQL 接口</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#元数据模版接口">元数据模版接口</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#构建元数据模版">构建元数据模版</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#修改模版节点信息">修改模版节点信息</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#挂载元数据模板">挂载元数据模板</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#卸载元数据模版">卸载元数据模版</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#查看元数据模版">查看元数据模版</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#删除元数据模版">删除元数据模版</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#对-pandas-的支持">对 Pandas 的支持</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#iotdb-testcontainer">IoTDB Testcontainer</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#iotdb-dbapi">IoTDB DBAPI</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#例子">例子</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#iotdb-sqlalchemy-dialect-实验性">IoTDB SQLAlchemy Dialect（实验性）</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#元数据模型映射">元数据模型映射</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#数据类型映射">数据类型映射</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#example">Example</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#给开发人员">给开发人员</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#介绍">介绍</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#依赖-1">依赖</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#编译-thrift-库并调试">编译 thrift 库并调试</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#session-客户端-使用示例">Session 客户端 &amp; 使用示例</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#测试">测试</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#其他工具">其他工具</a></li><!----><!--]--></ul></li><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level2" href="/#发版">发版</a></li><li><ul class="toc-list"><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#准备您的环境">准备您的环境</a></li><!----><!--]--><!--[--><li class="toc-item"><a class="vp-link toc-link level3" href="/#发版-1">发版</a></li><!----><!--]--></ul></li><!--]--></ul><div class="toc-marker" style="top:-1.7rem;"></div></div><!--[--><!----><!--]--></aside></div><!----><div class="theme-hope-content"><!--

    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.

--><h1 id="python-原生接口" tabindex="-1"><a class="header-anchor" href="#python-原生接口" aria-hidden="true">#</a> Python 原生接口</h1><h2 id="依赖" tabindex="-1"><a class="header-anchor" href="#依赖" aria-hidden="true">#</a> 依赖</h2><p>在使用 Python 原生接口包前，您需要安装 thrift (&gt;=0.13) 依赖。</p><h2 id="如何使用-示例" tabindex="-1"><a class="header-anchor" href="#如何使用-示例" aria-hidden="true">#</a> 如何使用 （示例）</h2><p>首先下载包：<code>pip3 install apache-iotdb</code></p><p>您可以从这里得到一个使用该包进行数据读写的例子：<a href="https://github.com/apache/iotdb/blob/master/client-py/SessionExample.py" target="_blank" rel="noopener noreferrer">Session Example<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a></p><p>关于对齐时间序列读写的例子：<a href="https://github.com/apache/iotdb/blob/master/client-py/SessionAlignedTimeseriesExample.py" target="_blank" rel="noopener noreferrer">Aligned Timeseries Session Example<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a></p><p>（您需要在文件的头部添加<code>import iotdb</code>）</p><p>或者：</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">from</span> iotdb<span class="token punctuation">.</span>Session <span class="token keyword">import</span> Session

ip <span class="token operator">=</span> <span class="token string">&quot;127.0.0.1&quot;</span>
port_ <span class="token operator">=</span> <span class="token string">&quot;6667&quot;</span>
username_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
password_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
session <span class="token operator">=</span> Session<span class="token punctuation">(</span>ip<span class="token punctuation">,</span> port_<span class="token punctuation">,</span> username_<span class="token punctuation">,</span> password_<span class="token punctuation">)</span>
session<span class="token punctuation">.</span><span class="token builtin">open</span><span class="token punctuation">(</span><span class="token boolean">False</span><span class="token punctuation">)</span>
zone <span class="token operator">=</span> session<span class="token punctuation">.</span>get_time_zone<span class="token punctuation">(</span><span class="token punctuation">)</span>
session<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="基本接口说明" tabindex="-1"><a class="header-anchor" href="#基本接口说明" aria-hidden="true">#</a> 基本接口说明</h2><p>下面将给出 Session 对应的接口的简要介绍和对应参数：</p><h3 id="初始化" tabindex="-1"><a class="header-anchor" href="#初始化" aria-hidden="true">#</a> 初始化</h3><ul><li>初始化 Session</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session <span class="token operator">=</span> Session<span class="token punctuation">(</span>
    ip<span class="token operator">=</span><span class="token string">&quot;127.0.0.1&quot;</span><span class="token punctuation">,</span>
    port<span class="token operator">=</span><span class="token string">&quot;6667&quot;</span><span class="token punctuation">,</span>
    user<span class="token operator">=</span><span class="token string">&quot;root&quot;</span><span class="token punctuation">,</span>
    password<span class="token operator">=</span><span class="token string">&quot;root&quot;</span><span class="token punctuation">,</span>
    fetch_size<span class="token operator">=</span><span class="token number">1024</span><span class="token punctuation">,</span>
    zone_id<span class="token operator">=</span><span class="token string">&quot;UTC+8&quot;</span><span class="token punctuation">,</span>
    enable_redirection<span class="token operator">=</span><span class="token boolean">True</span>
<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>初始化可连接多节点的 Session</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session <span class="token operator">=</span> Session<span class="token punctuation">.</span>init_from_node_urls<span class="token punctuation">(</span>
    node_urls<span class="token operator">=</span><span class="token punctuation">[</span><span class="token string">&quot;127.0.0.1:6667&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;127.0.0.1:6668&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;127.0.0.1:6669&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    user<span class="token operator">=</span><span class="token string">&quot;root&quot;</span><span class="token punctuation">,</span>
    password<span class="token operator">=</span><span class="token string">&quot;root&quot;</span><span class="token punctuation">,</span>
    fetch_size<span class="token operator">=</span><span class="token number">1024</span><span class="token punctuation">,</span>
    zone_id<span class="token operator">=</span><span class="token string">&quot;UTC+8&quot;</span><span class="token punctuation">,</span>
    enable_redirection<span class="token operator">=</span><span class="token boolean">True</span>
<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>开启 Session，并决定是否开启 RPC 压缩</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span><span class="token builtin">open</span><span class="token punctuation">(</span>enable_rpc_compression<span class="token operator">=</span><span class="token boolean">False</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>注意: 客户端的 RPC 压缩开启状态需和服务端一致</p><ul><li>关闭 Session</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="通过sessionpool管理session连接" tabindex="-1"><a class="header-anchor" href="#通过sessionpool管理session连接" aria-hidden="true">#</a> 通过SessionPool管理session连接</h3><p>利用SessionPool管理session，不需要再考虑如何重用session。当session连接到达pool的最大值时，获取session的请求会被阻塞，可以通过参数设置阻塞等待时间。每次session使用完需要使用putBack方法将session归还到SessionPool中管理。</p><h4 id="创建sessionpool" tabindex="-1"><a class="header-anchor" href="#创建sessionpool" aria-hidden="true">#</a> 创建SessionPool</h4><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>pool_config <span class="token operator">=</span> PoolConfig<span class="token punctuation">(</span>host<span class="token operator">=</span>ip<span class="token punctuation">,</span>port<span class="token operator">=</span>port<span class="token punctuation">,</span> user_name<span class="token operator">=</span>username<span class="token punctuation">,</span>
                         password<span class="token operator">=</span>password<span class="token punctuation">,</span> fetch_size<span class="token operator">=</span><span class="token number">1024</span><span class="token punctuation">,</span>
                         time_zone<span class="token operator">=</span><span class="token string">&quot;UTC+8&quot;</span><span class="token punctuation">,</span> max_retry<span class="token operator">=</span><span class="token number">3</span><span class="token punctuation">)</span>
max_pool_size <span class="token operator">=</span> <span class="token number">5</span>
wait_timeout_in_ms <span class="token operator">=</span> <span class="token number">3000</span>

<span class="token comment"># 通过配置参数创建连接池</span>
session_pool <span class="token operator">=</span> SessionPool<span class="token punctuation">(</span>pool_config<span class="token punctuation">,</span> max_pool_size<span class="token punctuation">,</span> wait_timeout_in_ms<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="通过分布式节点创建sessionpool" tabindex="-1"><a class="header-anchor" href="#通过分布式节点创建sessionpool" aria-hidden="true">#</a> 通过分布式节点创建SessionPool</h4><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>pool_config <span class="token operator">=</span> PoolConfig<span class="token punctuation">(</span>node_urls<span class="token operator">=</span>node_urls<span class="token operator">=</span><span class="token punctuation">[</span><span class="token string">&quot;127.0.0.1:6667&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;127.0.0.1:6668&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;127.0.0.1:6669&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span> user_name<span class="token operator">=</span>username<span class="token punctuation">,</span>
                         password<span class="token operator">=</span>password<span class="token punctuation">,</span> fetch_size<span class="token operator">=</span><span class="token number">1024</span><span class="token punctuation">,</span>
                         time_zone<span class="token operator">=</span><span class="token string">&quot;UTC+8&quot;</span><span class="token punctuation">,</span> max_retry<span class="token operator">=</span><span class="token number">3</span><span class="token punctuation">)</span>
max_pool_size <span class="token operator">=</span> <span class="token number">5</span>
wait_timeout_in_ms <span class="token operator">=</span> <span class="token number">3000</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="通过sessionpool获取session-使用完手动调用putback" tabindex="-1"><a class="header-anchor" href="#通过sessionpool获取session-使用完手动调用putback" aria-hidden="true">#</a> 通过SessionPool获取session，使用完手动调用PutBack</h4><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session <span class="token operator">=</span> session_pool<span class="token punctuation">.</span>get_session<span class="token punctuation">(</span><span class="token punctuation">)</span>
session<span class="token punctuation">.</span>set_storage_group<span class="token punctuation">(</span>STORAGE_GROUP_NAME<span class="token punctuation">)</span>
session<span class="token punctuation">.</span>create_time_series<span class="token punctuation">(</span>
  TIMESERIES_PATH<span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>BOOLEAN<span class="token punctuation">,</span> TSEncoding<span class="token punctuation">.</span>PLAIN<span class="token punctuation">,</span> Compressor<span class="token punctuation">.</span>SNAPPY
<span class="token punctuation">)</span>
<span class="token comment"># 使用完调用putBack归还</span>
session_pool<span class="token punctuation">.</span>put_back<span class="token punctuation">(</span>session<span class="token punctuation">)</span>
<span class="token comment"># 关闭sessionPool时同时关闭管理的session</span>
session_pool<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="数据定义接口-ddl" tabindex="-1"><a class="header-anchor" href="#数据定义接口-ddl" aria-hidden="true">#</a> 数据定义接口 DDL</h2><h3 id="database-管理" tabindex="-1"><a class="header-anchor" href="#database-管理" aria-hidden="true">#</a> Database 管理</h3><ul><li>设置 database</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>set_storage_group<span class="token punctuation">(</span>group_name<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>删除单个或多个 database</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>delete_storage_group<span class="token punctuation">(</span>group_name<span class="token punctuation">)</span>
session<span class="token punctuation">.</span>delete_storage_groups<span class="token punctuation">(</span>group_name_lst<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="时间序列管理" tabindex="-1"><a class="header-anchor" href="#时间序列管理" aria-hidden="true">#</a> 时间序列管理</h3><ul><li>创建单个或多个时间序列</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>create_time_series<span class="token punctuation">(</span>ts_path<span class="token punctuation">,</span> data_type<span class="token punctuation">,</span> encoding<span class="token punctuation">,</span> compressor<span class="token punctuation">,</span>
    props<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">,</span> tags<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">,</span> attributes<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">,</span> alias<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">)</span>
      
session<span class="token punctuation">.</span>create_multi_time_series<span class="token punctuation">(</span>
    ts_path_lst<span class="token punctuation">,</span> data_type_lst<span class="token punctuation">,</span> encoding_lst<span class="token punctuation">,</span> compressor_lst<span class="token punctuation">,</span>
    props_lst<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">,</span> tags_lst<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">,</span> attributes_lst<span class="token operator">=</span><span class="token boolean">None</span><span class="token punctuation">,</span> alias_lst<span class="token operator">=</span><span class="token boolean">None</span>
<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>创建对齐时间序列</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>create_aligned_time_series<span class="token punctuation">(</span>
    device_id<span class="token punctuation">,</span> measurements_lst<span class="token punctuation">,</span> data_type_lst<span class="token punctuation">,</span> encoding_lst<span class="token punctuation">,</span> compressor_lst
<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>注意：目前<strong>暂不支持</strong>使用传感器别名。</p><ul><li>删除一个或多个时间序列</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>delete_time_series<span class="token punctuation">(</span>paths_list<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>检测时间序列是否存在</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>check_time_series_exists<span class="token punctuation">(</span>path<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h2 id="数据操作接口-dml" tabindex="-1"><a class="header-anchor" href="#数据操作接口-dml" aria-hidden="true">#</a> 数据操作接口 DML</h2><h3 id="数据写入" tabindex="-1"><a class="header-anchor" href="#数据写入" aria-hidden="true">#</a> 数据写入</h3><p>推荐使用 insert_tablet 帮助提高写入效率</p><ul><li>插入一个 Tablet，Tablet 是一个设备若干行数据块，每一行的列都相同 <ul><li><strong>写入效率高</strong></li><li><strong>支持写入空值</strong> （0.13 版本起）</li></ul></li></ul><p>Python API 里目前有两种 Tablet 实现</p><ul><li>普通 Tablet</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>values_ <span class="token operator">=</span> <span class="token punctuation">[</span>
    <span class="token punctuation">[</span><span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token number">10</span><span class="token punctuation">,</span> <span class="token number">11</span><span class="token punctuation">,</span> <span class="token number">1.1</span><span class="token punctuation">,</span> <span class="token number">10011.1</span><span class="token punctuation">,</span> <span class="token string">&quot;test01&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span><span class="token boolean">True</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">11111</span><span class="token punctuation">,</span> <span class="token number">1.25</span><span class="token punctuation">,</span> <span class="token number">101.0</span><span class="token punctuation">,</span> <span class="token string">&quot;test02&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span><span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">188.1</span><span class="token punctuation">,</span> <span class="token number">688.25</span><span class="token punctuation">,</span> <span class="token string">&quot;test03&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span><span class="token boolean">True</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">,</span> <span class="token number">6.25</span><span class="token punctuation">,</span> <span class="token string">&quot;test04&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span>
timestamps_ <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">2</span><span class="token punctuation">,</span> <span class="token number">3</span><span class="token punctuation">,</span> <span class="token number">4</span><span class="token punctuation">]</span>
tablet_ <span class="token operator">=</span> Tablet<span class="token punctuation">(</span>
    device_id<span class="token punctuation">,</span> measurements_<span class="token punctuation">,</span> data_types_<span class="token punctuation">,</span> values_<span class="token punctuation">,</span> timestamps_
<span class="token punctuation">)</span>
session<span class="token punctuation">.</span>insert_tablet<span class="token punctuation">(</span>tablet_<span class="token punctuation">)</span>

values_ <span class="token operator">=</span> <span class="token punctuation">[</span>
    <span class="token punctuation">[</span><span class="token boolean">None</span><span class="token punctuation">,</span> <span class="token number">10</span><span class="token punctuation">,</span> <span class="token number">11</span><span class="token punctuation">,</span> <span class="token number">1.1</span><span class="token punctuation">,</span> <span class="token number">10011.1</span><span class="token punctuation">,</span> <span class="token string">&quot;test01&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span><span class="token boolean">True</span><span class="token punctuation">,</span> <span class="token boolean">None</span><span class="token punctuation">,</span> <span class="token number">11111</span><span class="token punctuation">,</span> <span class="token number">1.25</span><span class="token punctuation">,</span> <span class="token number">101.0</span><span class="token punctuation">,</span> <span class="token string">&quot;test02&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span><span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token boolean">None</span><span class="token punctuation">,</span> <span class="token number">188.1</span><span class="token punctuation">,</span> <span class="token number">688.25</span><span class="token punctuation">,</span> <span class="token string">&quot;test03&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    <span class="token punctuation">[</span><span class="token boolean">True</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">,</span> <span class="token boolean">None</span><span class="token punctuation">,</span> <span class="token boolean">None</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span>
timestamps_ <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token number">16</span><span class="token punctuation">,</span> <span class="token number">17</span><span class="token punctuation">,</span> <span class="token number">18</span><span class="token punctuation">,</span> <span class="token number">19</span><span class="token punctuation">]</span>
tablet_ <span class="token operator">=</span> Tablet<span class="token punctuation">(</span>
    device_id<span class="token punctuation">,</span> measurements_<span class="token punctuation">,</span> data_types_<span class="token punctuation">,</span> values_<span class="token punctuation">,</span> timestamps_
<span class="token punctuation">)</span>
session<span class="token punctuation">.</span>insert_tablet<span class="token punctuation">(</span>tablet_<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>Numpy Tablet</li></ul><p>相较于普通 Tablet，Numpy Tablet 使用 <a href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html" target="_blank" rel="noopener noreferrer">numpy.ndarray<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a> 来记录数值型数据。<br> 内存占用和序列化耗时会降低很多，写入效率也会有很大提升。</p><p><strong>注意</strong></p><ol><li>Tablet 中的每一列时间戳和值记录为一个 ndarray</li><li>Numpy Tablet 只支持大端类型数据，ndarray 构建时如果不指定数据类型会使用小端，因此推荐在构建 ndarray 时指定下面例子中类型使用大端。如果不指定，IoTDB Python客户端也会进行大小端转换，不影响使用正确性。</li></ol><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">import</span> numpy <span class="token keyword">as</span> np
data_types_ <span class="token operator">=</span> <span class="token punctuation">[</span>
    TSDataType<span class="token punctuation">.</span>BOOLEAN<span class="token punctuation">,</span>
    TSDataType<span class="token punctuation">.</span>INT32<span class="token punctuation">,</span>
    TSDataType<span class="token punctuation">.</span>INT64<span class="token punctuation">,</span>
    TSDataType<span class="token punctuation">.</span>FLOAT<span class="token punctuation">,</span>
    TSDataType<span class="token punctuation">.</span>DOUBLE<span class="token punctuation">,</span>
    TSDataType<span class="token punctuation">.</span>TEXT<span class="token punctuation">,</span>
<span class="token punctuation">]</span>
np_values_ <span class="token operator">=</span> <span class="token punctuation">[</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token boolean">True</span><span class="token punctuation">,</span> <span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token boolean">True</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>BOOLEAN<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">10</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>INT32<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">11</span><span class="token punctuation">,</span> <span class="token number">11111</span><span class="token punctuation">,</span> <span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>INT64<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">1.1</span><span class="token punctuation">,</span> <span class="token number">1.25</span><span class="token punctuation">,</span> <span class="token number">188.1</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>FLOAT<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">10011.1</span><span class="token punctuation">,</span> <span class="token number">101.0</span><span class="token punctuation">,</span> <span class="token number">688.25</span><span class="token punctuation">,</span> <span class="token number">6.25</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>DOUBLE<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string">&quot;test01&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;test02&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;test03&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;test04&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>TEXT<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span>
np_timestamps_ <span class="token operator">=</span> np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">2</span><span class="token punctuation">,</span> <span class="token number">3</span><span class="token punctuation">,</span> <span class="token number">4</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>INT64<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
np_tablet_ <span class="token operator">=</span> NumpyTablet<span class="token punctuation">(</span>
  device_id<span class="token punctuation">,</span> measurements_<span class="token punctuation">,</span> data_types_<span class="token punctuation">,</span> np_values_<span class="token punctuation">,</span> np_timestamps_
<span class="token punctuation">)</span>
session<span class="token punctuation">.</span>insert_tablet<span class="token punctuation">(</span>np_tablet_<span class="token punctuation">)</span>

<span class="token comment"># insert one numpy tablet with None into the database.</span>
np_values_ <span class="token operator">=</span> <span class="token punctuation">[</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token boolean">True</span><span class="token punctuation">,</span> <span class="token boolean">False</span><span class="token punctuation">,</span> <span class="token boolean">True</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>BOOLEAN<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">10</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>INT32<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">11</span><span class="token punctuation">,</span> <span class="token number">11111</span><span class="token punctuation">,</span> <span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>INT64<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">1.1</span><span class="token punctuation">,</span> <span class="token number">1.25</span><span class="token punctuation">,</span> <span class="token number">188.1</span><span class="token punctuation">,</span> <span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>FLOAT<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">10011.1</span><span class="token punctuation">,</span> <span class="token number">101.0</span><span class="token punctuation">,</span> <span class="token number">688.25</span><span class="token punctuation">,</span> <span class="token number">6.25</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>DOUBLE<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token string">&quot;test01&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;test02&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;test03&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;test04&quot;</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>TEXT<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span>
np_timestamps_ <span class="token operator">=</span> np<span class="token punctuation">.</span>array<span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token number">98</span><span class="token punctuation">,</span> <span class="token number">99</span><span class="token punctuation">,</span> <span class="token number">100</span><span class="token punctuation">,</span> <span class="token number">101</span><span class="token punctuation">]</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>INT64<span class="token punctuation">.</span>np_dtype<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
np_bitmaps_ <span class="token operator">=</span> <span class="token punctuation">[</span><span class="token punctuation">]</span>
<span class="token keyword">for</span> i <span class="token keyword">in</span> <span class="token builtin">range</span><span class="token punctuation">(</span><span class="token builtin">len</span><span class="token punctuation">(</span>measurements_<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
    np_bitmaps_<span class="token punctuation">.</span>append<span class="token punctuation">(</span>BitMap<span class="token punctuation">(</span><span class="token builtin">len</span><span class="token punctuation">(</span>np_timestamps_<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
np_bitmaps_<span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">.</span>mark<span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span>
np_bitmaps_<span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">]</span><span class="token punctuation">.</span>mark<span class="token punctuation">(</span><span class="token number">1</span><span class="token punctuation">)</span>
np_bitmaps_<span class="token punctuation">[</span><span class="token number">2</span><span class="token punctuation">]</span><span class="token punctuation">.</span>mark<span class="token punctuation">(</span><span class="token number">2</span><span class="token punctuation">)</span>
np_bitmaps_<span class="token punctuation">[</span><span class="token number">4</span><span class="token punctuation">]</span><span class="token punctuation">.</span>mark<span class="token punctuation">(</span><span class="token number">3</span><span class="token punctuation">)</span>
np_bitmaps_<span class="token punctuation">[</span><span class="token number">5</span><span class="token punctuation">]</span><span class="token punctuation">.</span>mark<span class="token punctuation">(</span><span class="token number">3</span><span class="token punctuation">)</span>
np_tablet_with_none <span class="token operator">=</span> NumpyTablet<span class="token punctuation">(</span>
    device_id<span class="token punctuation">,</span> measurements_<span class="token punctuation">,</span> data_types_<span class="token punctuation">,</span> np_values_<span class="token punctuation">,</span> np_timestamps_<span class="token punctuation">,</span> np_bitmaps_
<span class="token punctuation">)</span>
session<span class="token punctuation">.</span>insert_tablet<span class="token punctuation">(</span>np_tablet_with_none<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>插入多个 Tablet</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>insert_tablets<span class="token punctuation">(</span>tablet_lst<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>插入一个 Record，一个 Record 是一个设备一个时间戳下多个测点的数据。</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>insert_record<span class="token punctuation">(</span>device_id<span class="token punctuation">,</span> timestamp<span class="token punctuation">,</span> measurements_<span class="token punctuation">,</span> data_types_<span class="token punctuation">,</span> values_<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>插入多个 Record</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>insert_records<span class="token punctuation">(</span>
    device_ids_<span class="token punctuation">,</span> time_list_<span class="token punctuation">,</span> measurements_list_<span class="token punctuation">,</span> data_type_list_<span class="token punctuation">,</span> values_list_
    <span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>插入同属于一个 device 的多个 Record</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>insert_records_of_one_device<span class="token punctuation">(</span>device_id<span class="token punctuation">,</span> time_list<span class="token punctuation">,</span> measurements_list<span class="token punctuation">,</span> data_types_list<span class="token punctuation">,</span> values_list<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="带有类型推断的写入" tabindex="-1"><a class="header-anchor" href="#带有类型推断的写入" aria-hidden="true">#</a> 带有类型推断的写入</h3><p>当数据均是 String 类型时，我们可以使用如下接口，根据 value 的值进行类型推断。例如：value 为 &quot;true&quot; ，就可以自动推断为布尔类型。value 为 &quot;3.2&quot; ，就可以自动推断为数值类型。服务器需要做类型推断，可能会有额外耗时，速度较无需类型推断的写入慢</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>insert_str_record<span class="token punctuation">(</span>device_id<span class="token punctuation">,</span> timestamp<span class="token punctuation">,</span> measurements<span class="token punctuation">,</span> string_values<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="对齐时间序列的写入" tabindex="-1"><a class="header-anchor" href="#对齐时间序列的写入" aria-hidden="true">#</a> 对齐时间序列的写入</h3><p>对齐时间序列的写入使用 insert_aligned_xxx 接口，其余与上述接口类似：</p><ul><li>insert_aligned_record</li><li>insert_aligned_records</li><li>insert_aligned_records_of_one_device</li><li>insert_aligned_tablet</li><li>insert_aligned_tablets</li></ul><h2 id="iotdb-sql-接口" tabindex="-1"><a class="header-anchor" href="#iotdb-sql-接口" aria-hidden="true">#</a> IoTDB-SQL 接口</h2><ul><li>执行查询语句</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>execute_query_statement<span class="token punctuation">(</span>sql<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>执行非查询语句</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>execute_non_query_statement<span class="token punctuation">(</span>sql<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>执行语句</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>execute_statement<span class="token punctuation">(</span>sql<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h2 id="元数据模版接口" tabindex="-1"><a class="header-anchor" href="#元数据模版接口" aria-hidden="true">#</a> 元数据模版接口</h2><h3 id="构建元数据模版" tabindex="-1"><a class="header-anchor" href="#构建元数据模版" aria-hidden="true">#</a> 构建元数据模版</h3><ol><li>首先构建 Template 类</li><li>添加子节点 MeasurementNode</li><li>调用创建元数据模版接口</li></ol><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>template <span class="token operator">=</span> Template<span class="token punctuation">(</span>name<span class="token operator">=</span>template_name<span class="token punctuation">,</span> share_time<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">)</span>

m_node_x <span class="token operator">=</span> MeasurementNode<span class="token punctuation">(</span><span class="token string">&quot;x&quot;</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>FLOAT<span class="token punctuation">,</span> TSEncoding<span class="token punctuation">.</span>RLE<span class="token punctuation">,</span> Compressor<span class="token punctuation">.</span>SNAPPY<span class="token punctuation">)</span>
m_node_y <span class="token operator">=</span> MeasurementNode<span class="token punctuation">(</span><span class="token string">&quot;y&quot;</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>FLOAT<span class="token punctuation">,</span> TSEncoding<span class="token punctuation">.</span>RLE<span class="token punctuation">,</span> Compressor<span class="token punctuation">.</span>SNAPPY<span class="token punctuation">)</span>
m_node_z <span class="token operator">=</span> MeasurementNode<span class="token punctuation">(</span><span class="token string">&quot;z&quot;</span><span class="token punctuation">,</span> TSDataType<span class="token punctuation">.</span>FLOAT<span class="token punctuation">,</span> TSEncoding<span class="token punctuation">.</span>RLE<span class="token punctuation">,</span> Compressor<span class="token punctuation">.</span>SNAPPY<span class="token punctuation">)</span>

template<span class="token punctuation">.</span>add_template<span class="token punctuation">(</span>m_node_x<span class="token punctuation">)</span>
template<span class="token punctuation">.</span>add_template<span class="token punctuation">(</span>m_node_y<span class="token punctuation">)</span>
template<span class="token punctuation">.</span>add_template<span class="token punctuation">(</span>m_node_z<span class="token punctuation">)</span>

session<span class="token punctuation">.</span>create_schema_template<span class="token punctuation">(</span>template<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="修改模版节点信息" tabindex="-1"><a class="header-anchor" href="#修改模版节点信息" aria-hidden="true">#</a> 修改模版节点信息</h3><p>修改模版节点，其中修改的模版必须已经被创建。以下函数能够在已经存在的模版中增加或者删除物理量</p><ul><li>在模版中增加实体</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>add_measurements_in_template<span class="token punctuation">(</span>template_name<span class="token punctuation">,</span> measurements_path<span class="token punctuation">,</span> data_types<span class="token punctuation">,</span> encodings<span class="token punctuation">,</span> compressors<span class="token punctuation">,</span> is_aligned<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>在模版中删除物理量</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>delete_node_in_template<span class="token punctuation">(</span>template_name<span class="token punctuation">,</span> path<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="挂载元数据模板" tabindex="-1"><a class="header-anchor" href="#挂载元数据模板" aria-hidden="true">#</a> 挂载元数据模板</h3><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>set_schema_template<span class="token punctuation">(</span>template_name<span class="token punctuation">,</span> prefix_path<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="卸载元数据模版" tabindex="-1"><a class="header-anchor" href="#卸载元数据模版" aria-hidden="true">#</a> 卸载元数据模版</h3><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>unset_schema_template<span class="token punctuation">(</span>template_name<span class="token punctuation">,</span> prefix_path<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="查看元数据模版" tabindex="-1"><a class="header-anchor" href="#查看元数据模版" aria-hidden="true">#</a> 查看元数据模版</h3><ul><li>查看所有的元数据模版</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>show_all_templates<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>查看元数据模版中的物理量个数</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>count_measurements_in_template<span class="token punctuation">(</span>template_name<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>判断某个节点是否为物理量，该节点必须已经在元数据模版中</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>count_measurements_in_template<span class="token punctuation">(</span>template_name<span class="token punctuation">,</span> path<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>判断某个路径是否在元数据模版中，这个路径有可能不在元数据模版中</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>is_path_exist_in_template<span class="token punctuation">(</span>template_name<span class="token punctuation">,</span> path<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>查看某个元数据模板下的物理量</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>show_measurements_in_template<span class="token punctuation">(</span>template_name<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>查看挂载了某个元数据模板的路径前缀</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>show_paths_template_set_on<span class="token punctuation">(</span>template_name<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><ul><li>查看使用了某个元数据模板（即序列已创建）的路径前缀</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>show_paths_template_using_on<span class="token punctuation">(</span>template_name<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="删除元数据模版" tabindex="-1"><a class="header-anchor" href="#删除元数据模版" aria-hidden="true">#</a> 删除元数据模版</h3><p>删除已经存在的元数据模版，不支持删除已经挂载的模版</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>session<span class="token punctuation">.</span>drop_schema_template<span class="token punctuation">(</span><span class="token string">&quot;template_python&quot;</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h2 id="对-pandas-的支持" tabindex="-1"><a class="header-anchor" href="#对-pandas-的支持" aria-hidden="true">#</a> 对 Pandas 的支持</h2><p>我们支持将查询结果轻松地转换为 <a href="https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html" target="_blank" rel="noopener noreferrer">Pandas Dataframe<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a>。</p><p>SessionDataSet 有一个方法<code>.todf()</code>，它的作用是消费 SessionDataSet 中的数据，并将数据转换为 pandas dataframe。</p><p>例子：</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">from</span> iotdb<span class="token punctuation">.</span>Session <span class="token keyword">import</span> Session

ip <span class="token operator">=</span> <span class="token string">&quot;127.0.0.1&quot;</span>
port_ <span class="token operator">=</span> <span class="token string">&quot;6667&quot;</span>
username_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
password_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
session <span class="token operator">=</span> Session<span class="token punctuation">(</span>ip<span class="token punctuation">,</span> port_<span class="token punctuation">,</span> username_<span class="token punctuation">,</span> password_<span class="token punctuation">)</span>
session<span class="token punctuation">.</span><span class="token builtin">open</span><span class="token punctuation">(</span><span class="token boolean">False</span><span class="token punctuation">)</span>
result <span class="token operator">=</span> session<span class="token punctuation">.</span>execute_query_statement<span class="token punctuation">(</span><span class="token string">&quot;SELECT ** FROM root&quot;</span><span class="token punctuation">)</span>

<span class="token comment"># Transform to Pandas Dataset</span>
df <span class="token operator">=</span> result<span class="token punctuation">.</span>todf<span class="token punctuation">(</span><span class="token punctuation">)</span>

session<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>

<span class="token comment"># Now you can work with the dataframe</span>
df <span class="token operator">=</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="iotdb-testcontainer" tabindex="-1"><a class="header-anchor" href="#iotdb-testcontainer" aria-hidden="true">#</a> IoTDB Testcontainer</h2><p>Python 客户端对测试的支持是基于<code>testcontainers</code>库 (<a href="https://testcontainers-python.readthedocs.io/en/latest/index.html" target="_blank" rel="noopener noreferrer">https://testcontainers-python.readthedocs.io/en/latest/index.html<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a>) 的，如果您想使用该特性，就需要将其安装到您的项目中。</p><p>要在 Docker 容器中启动（和停止）一个 IoTDB 数据库，只需这样做：</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">class</span> <span class="token class-name">MyTestCase</span><span class="token punctuation">(</span>unittest<span class="token punctuation">.</span>TestCase<span class="token punctuation">)</span><span class="token punctuation">:</span>

    <span class="token keyword">def</span> <span class="token function">test_something</span><span class="token punctuation">(</span>self<span class="token punctuation">)</span><span class="token punctuation">:</span>
        <span class="token keyword">with</span> IoTDBContainer<span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token keyword">as</span> c<span class="token punctuation">:</span>
            session <span class="token operator">=</span> Session<span class="token punctuation">(</span><span class="token string">&quot;localhost&quot;</span><span class="token punctuation">,</span> c<span class="token punctuation">.</span>get_exposed_port<span class="token punctuation">(</span><span class="token number">6667</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token string">&quot;root&quot;</span><span class="token punctuation">,</span> <span class="token string">&quot;root&quot;</span><span class="token punctuation">)</span>
            session<span class="token punctuation">.</span><span class="token builtin">open</span><span class="token punctuation">(</span><span class="token boolean">False</span><span class="token punctuation">)</span>
            result <span class="token operator">=</span> session<span class="token punctuation">.</span>execute_query_statement<span class="token punctuation">(</span><span class="token string">&quot;SHOW TIMESERIES&quot;</span><span class="token punctuation">)</span>
            <span class="token keyword">print</span><span class="token punctuation">(</span>result<span class="token punctuation">)</span>
            session<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>默认情况下，它会拉取最新的 IoTDB 镜像 <code>apache/iotdb:latest</code>进行测试，如果您想指定待测 IoTDB 的版本，您只需要将版本信息像这样声明：<code>IoTDBContainer(&quot;apache/iotdb:0.12.0&quot;)</code>，此时，您就会得到一个<code>0.12.0</code>版本的 IoTDB 实例。</p><h2 id="iotdb-dbapi" tabindex="-1"><a class="header-anchor" href="#iotdb-dbapi" aria-hidden="true">#</a> IoTDB DBAPI</h2><p>IoTDB DBAPI 遵循 Python DB API 2.0 规范 (<a href="https://peps.python.org/pep-0249/" target="_blank" rel="noopener noreferrer">https://peps.python.org/pep-0249/<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a>)，实现了通过Python语言访问数据库的通用接口。</p><h3 id="例子" tabindex="-1"><a class="header-anchor" href="#例子" aria-hidden="true">#</a> 例子</h3><ul><li>初始化</li></ul><p>初始化的参数与Session部分保持一致（sqlalchemy_mode参数除外，该参数仅在SQLAlchemy方言中使用）</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">from</span> iotdb<span class="token punctuation">.</span>dbapi <span class="token keyword">import</span> connect

ip <span class="token operator">=</span> <span class="token string">&quot;127.0.0.1&quot;</span>
port_ <span class="token operator">=</span> <span class="token string">&quot;6667&quot;</span>
username_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
password_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
conn <span class="token operator">=</span> connect<span class="token punctuation">(</span>ip<span class="token punctuation">,</span> port_<span class="token punctuation">,</span> username_<span class="token punctuation">,</span> password_<span class="token punctuation">,</span>fetch_size<span class="token operator">=</span><span class="token number">1024</span><span class="token punctuation">,</span>zone_id<span class="token operator">=</span><span class="token string">&quot;UTC+8&quot;</span><span class="token punctuation">,</span>sqlalchemy_mode<span class="token operator">=</span><span class="token boolean">False</span><span class="token punctuation">)</span>
cursor <span class="token operator">=</span> conn<span class="token punctuation">.</span>cursor<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>执行简单的SQL语句</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>cursor<span class="token punctuation">.</span>execute<span class="token punctuation">(</span><span class="token string">&quot;SELECT ** FROM root&quot;</span><span class="token punctuation">)</span>
<span class="token keyword">for</span> row <span class="token keyword">in</span> cursor<span class="token punctuation">.</span>fetchall<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span>row<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>执行带有参数的SQL语句</li></ul><p>IoTDB DBAPI 支持pyformat风格的参数</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>cursor<span class="token punctuation">.</span>execute<span class="token punctuation">(</span><span class="token string">&quot;SELECT ** FROM root WHERE time &lt; %(time)s&quot;</span><span class="token punctuation">,</span><span class="token punctuation">{</span><span class="token string">&quot;time&quot;</span><span class="token punctuation">:</span><span class="token string">&quot;2017-11-01T00:08:00.000&quot;</span><span class="token punctuation">}</span><span class="token punctuation">)</span>
<span class="token keyword">for</span> row <span class="token keyword">in</span> cursor<span class="token punctuation">.</span>fetchall<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span>row<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>批量执行带有参数的SQL语句</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>seq_of_parameters <span class="token operator">=</span> <span class="token punctuation">[</span>
    <span class="token punctuation">{</span><span class="token string">&quot;timestamp&quot;</span><span class="token punctuation">:</span> <span class="token number">1</span><span class="token punctuation">,</span> <span class="token string">&quot;temperature&quot;</span><span class="token punctuation">:</span> <span class="token number">1</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">{</span><span class="token string">&quot;timestamp&quot;</span><span class="token punctuation">:</span> <span class="token number">2</span><span class="token punctuation">,</span> <span class="token string">&quot;temperature&quot;</span><span class="token punctuation">:</span> <span class="token number">2</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">{</span><span class="token string">&quot;timestamp&quot;</span><span class="token punctuation">:</span> <span class="token number">3</span><span class="token punctuation">,</span> <span class="token string">&quot;temperature&quot;</span><span class="token punctuation">:</span> <span class="token number">3</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">{</span><span class="token string">&quot;timestamp&quot;</span><span class="token punctuation">:</span> <span class="token number">4</span><span class="token punctuation">,</span> <span class="token string">&quot;temperature&quot;</span><span class="token punctuation">:</span> <span class="token number">4</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">{</span><span class="token string">&quot;timestamp&quot;</span><span class="token punctuation">:</span> <span class="token number">5</span><span class="token punctuation">,</span> <span class="token string">&quot;temperature&quot;</span><span class="token punctuation">:</span> <span class="token number">5</span><span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span>
sql <span class="token operator">=</span> <span class="token string">&quot;insert into root.cursor(timestamp,temperature) values(%(timestamp)s,%(temperature)s)&quot;</span>
cursor<span class="token punctuation">.</span>executemany<span class="token punctuation">(</span>sql<span class="token punctuation">,</span>seq_of_parameters<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>关闭连接</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code>cursor<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
conn<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="iotdb-sqlalchemy-dialect-实验性" tabindex="-1"><a class="header-anchor" href="#iotdb-sqlalchemy-dialect-实验性" aria-hidden="true">#</a> IoTDB SQLAlchemy Dialect（实验性）</h2><p>IoTDB的SQLAlchemy方言主要是为了适配Apache superset而编写的，该部分仍在完善中，请勿在生产环境中使用！</p><h3 id="元数据模型映射" tabindex="-1"><a class="header-anchor" href="#元数据模型映射" aria-hidden="true">#</a> 元数据模型映射</h3><p>SQLAlchemy 所使用的数据模型为关系数据模型，这种数据模型通过表格来描述不同实体之间的关系。<br> 而 IoTDB 的数据模型为层次数据模型，通过树状结构来对数据进行组织。<br> 为了使 IoTDB 能够适配 SQLAlchemy 的方言，需要对 IoTDB 中原有的数据模型进行重新组织，<br> 把 IoTDB 的数据模型转换成 SQLAlchemy 的数据模型。</p><p>IoTDB 中的元数据有：</p><ol><li>Database：数据库</li><li>Path：存储路径</li><li>Entity：实体</li><li>Measurement：物理量</li></ol><p>SQLAlchemy 中的元数据有：</p><ol><li>Schema：数据模式</li><li>Table：数据表</li><li>Column：数据列</li></ol><p>它们之间的映射关系为：</p><table><thead><tr><th>SQLAlchemy中的元数据</th><th>IoTDB中对应的元数据</th></tr></thead><tbody><tr><td>Schema</td><td>Database</td></tr><tr><td>Table</td><td>Path ( from database to entity ) + Entity</td></tr><tr><td>Column</td><td>Measurement</td></tr></tbody></table><p>下图更加清晰的展示了二者的映射关系：</p><figure><img src="https://alioss.timecho.com/docs/img/UserGuide/API/IoTDB-SQLAlchemy/sqlalchemy-to-iotdb.png?raw=true" alt="sqlalchemy-to-iotdb" tabindex="0" loading="lazy"><figcaption>sqlalchemy-to-iotdb</figcaption></figure><h3 id="数据类型映射" tabindex="-1"><a class="header-anchor" href="#数据类型映射" aria-hidden="true">#</a> 数据类型映射</h3><table><thead><tr><th>IoTDB 中的数据类型</th><th>SQLAlchemy 中的数据类型</th></tr></thead><tbody><tr><td>BOOLEAN</td><td>Boolean</td></tr><tr><td>INT32</td><td>Integer</td></tr><tr><td>INT64</td><td>BigInteger</td></tr><tr><td>FLOAT</td><td>Float</td></tr><tr><td>DOUBLE</td><td>Float</td></tr><tr><td>TEXT</td><td>Text</td></tr><tr><td>LONG</td><td>BigInteger</td></tr></tbody></table><h3 id="example" tabindex="-1"><a class="header-anchor" href="#example" aria-hidden="true">#</a> Example</h3><ul><li>执行语句</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">from</span> sqlalchemy <span class="token keyword">import</span> create_engine

engine <span class="token operator">=</span> create_engine<span class="token punctuation">(</span><span class="token string">&quot;iotdb://root:root@127.0.0.1:6667&quot;</span><span class="token punctuation">)</span>
connect <span class="token operator">=</span> engine<span class="token punctuation">.</span>connect<span class="token punctuation">(</span><span class="token punctuation">)</span>
result <span class="token operator">=</span> connect<span class="token punctuation">.</span>execute<span class="token punctuation">(</span><span class="token string">&quot;SELECT ** FROM root&quot;</span><span class="token punctuation">)</span>
<span class="token keyword">for</span> row <span class="token keyword">in</span> result<span class="token punctuation">.</span>fetchall<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span>row<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><ul><li>ORM (目前只支持简单的查询)</li></ul><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">from</span> sqlalchemy <span class="token keyword">import</span> create_engine<span class="token punctuation">,</span> Column<span class="token punctuation">,</span> Float<span class="token punctuation">,</span> BigInteger<span class="token punctuation">,</span> MetaData
<span class="token keyword">from</span> sqlalchemy<span class="token punctuation">.</span>ext<span class="token punctuation">.</span>declarative <span class="token keyword">import</span> declarative_base
<span class="token keyword">from</span> sqlalchemy<span class="token punctuation">.</span>orm <span class="token keyword">import</span> sessionmaker

metadata <span class="token operator">=</span> MetaData<span class="token punctuation">(</span>
    schema<span class="token operator">=</span><span class="token string">&#39;root.factory&#39;</span>
<span class="token punctuation">)</span>
Base <span class="token operator">=</span> declarative_base<span class="token punctuation">(</span>metadata<span class="token operator">=</span>metadata<span class="token punctuation">)</span>


<span class="token keyword">class</span> <span class="token class-name">Device</span><span class="token punctuation">(</span>Base<span class="token punctuation">)</span><span class="token punctuation">:</span>
    __tablename__ <span class="token operator">=</span> <span class="token string">&quot;room2.device1&quot;</span>
    Time <span class="token operator">=</span> Column<span class="token punctuation">(</span>BigInteger<span class="token punctuation">,</span> primary_key<span class="token operator">=</span><span class="token boolean">True</span><span class="token punctuation">)</span>
    temperature <span class="token operator">=</span> Column<span class="token punctuation">(</span>Float<span class="token punctuation">)</span>
    status <span class="token operator">=</span> Column<span class="token punctuation">(</span>Float<span class="token punctuation">)</span>


engine <span class="token operator">=</span> create_engine<span class="token punctuation">(</span><span class="token string">&quot;iotdb://root:root@127.0.0.1:6667&quot;</span><span class="token punctuation">)</span>

DbSession <span class="token operator">=</span> sessionmaker<span class="token punctuation">(</span>bind<span class="token operator">=</span>engine<span class="token punctuation">)</span>
session <span class="token operator">=</span> DbSession<span class="token punctuation">(</span><span class="token punctuation">)</span>

res <span class="token operator">=</span> session<span class="token punctuation">.</span>query<span class="token punctuation">(</span>Device<span class="token punctuation">.</span>status<span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token builtin">filter</span><span class="token punctuation">(</span>Device<span class="token punctuation">.</span>temperature <span class="token operator">&gt;</span> <span class="token number">1</span><span class="token punctuation">)</span>

<span class="token keyword">for</span> row <span class="token keyword">in</span> res<span class="token punctuation">:</span>
    <span class="token keyword">print</span><span class="token punctuation">(</span>row<span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="给开发人员" tabindex="-1"><a class="header-anchor" href="#给开发人员" aria-hidden="true">#</a> 给开发人员</h2><h3 id="介绍" tabindex="-1"><a class="header-anchor" href="#介绍" aria-hidden="true">#</a> 介绍</h3><p>这是一个使用 thrift rpc 接口连接到 IoTDB 的示例。在 Windows 和 Linux 上操作几乎是一样的，但要注意路径分隔符等不同之处。</p><h3 id="依赖-1" tabindex="-1"><a class="header-anchor" href="#依赖-1" aria-hidden="true">#</a> 依赖</h3><p>首选 Python3.7 或更高版本。</p><p>必须安装 thrift（0.11.0 或更高版本）才能将 thrift 文件编译为 Python 代码。下面是官方的安装教程，最终，您应该得到一个 thrift 可执行文件。</p><div class="language-text line-numbers-mode" data-ext="text"><pre class="language-text"><code>http://thrift.apache.org/docs/install/
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>在开始之前，您还需要在 Python 环境中安装<code>requirements_dev.txt</code>中的其他依赖：</p><div class="language-bash line-numbers-mode" data-ext="sh"><pre class="language-bash"><code>pip <span class="token function">install</span> <span class="token parameter variable">-r</span> requirements_dev.txt
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><h3 id="编译-thrift-库并调试" tabindex="-1"><a class="header-anchor" href="#编译-thrift-库并调试" aria-hidden="true">#</a> 编译 thrift 库并调试</h3><p>在 IoTDB 源代码文件夹的根目录下，运行<code>mvn clean generate-sources -pl iotdb-client/client-py -am</code>，</p><p>这个指令将自动删除<code>iotdb/thrift</code>中的文件，并使用新生成的 thrift 文件重新填充该文件夹。</p><p>这个文件夹在 git 中会被忽略，并且<strong>永远不应该被推到 git 中！</strong></p><p><strong>注意</strong>不要将<code>iotdb/thrift</code>上传到 git 仓库中 ！</p><h3 id="session-客户端-使用示例" tabindex="-1"><a class="header-anchor" href="#session-客户端-使用示例" aria-hidden="true">#</a> Session 客户端 &amp; 使用示例</h3><p>我们将 thrift 接口打包到<code>client-py/src/iotdb/session.py </code>中（与 Java 版本类似），还提供了一个示例文件<code>client-py/src/SessionExample.py</code>来说明如何使用 Session 模块。请仔细阅读。</p><p>另一个简单的例子：</p><div class="language-python line-numbers-mode" data-ext="py"><pre class="language-python"><code><span class="token keyword">from</span> iotdb<span class="token punctuation">.</span>Session <span class="token keyword">import</span> Session

ip <span class="token operator">=</span> <span class="token string">&quot;127.0.0.1&quot;</span>
port_ <span class="token operator">=</span> <span class="token string">&quot;6667&quot;</span>
username_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
password_ <span class="token operator">=</span> <span class="token string">&quot;root&quot;</span>
session <span class="token operator">=</span> Session<span class="token punctuation">(</span>ip<span class="token punctuation">,</span> port_<span class="token punctuation">,</span> username_<span class="token punctuation">,</span> password_<span class="token punctuation">)</span>
session<span class="token punctuation">.</span><span class="token builtin">open</span><span class="token punctuation">(</span><span class="token boolean">False</span><span class="token punctuation">)</span>
zone <span class="token operator">=</span> session<span class="token punctuation">.</span>get_time_zone<span class="token punctuation">(</span><span class="token punctuation">)</span>
session<span class="token punctuation">.</span>close<span class="token punctuation">(</span><span class="token punctuation">)</span>
</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="测试" tabindex="-1"><a class="header-anchor" href="#测试" aria-hidden="true">#</a> 测试</h3><p>请在<code>tests</code>文件夹中添加自定义测试。</p><p>要运行所有的测试，只需在根目录中运行<code>pytest . </code>即可。</p><p><strong>注意</strong>一些测试需要在您的系统上使用 docker，因为测试的 IoTDB 实例是使用 <a href="https://testcontainers-python.readthedocs.io/en/latest/index.html" target="_blank" rel="noopener noreferrer">testcontainers<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a> 在 docker 容器中启动的。</p><h3 id="其他工具" tabindex="-1"><a class="header-anchor" href="#其他工具" aria-hidden="true">#</a> 其他工具</h3><p><a href="https://pypi.org/project/black/" target="_blank" rel="noopener noreferrer">black<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a> 和 <a href="https://pypi.org/project/flake8/" target="_blank" rel="noopener noreferrer">flake8<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span></a> 分别用于自动格式化和 linting。<br> 它们可以通过 <code>black .</code> 或 <code>flake8 .</code> 分别运行。</p><h2 id="发版" tabindex="-1"><a class="header-anchor" href="#发版" aria-hidden="true">#</a> 发版</h2><p>要进行发版，</p><p>只需确保您生成了正确的 thrift 代码，</p><p>运行了 linting 并进行了自动格式化，</p><p>然后，确保所有测试都正常通过（通过<code>pytest . </code>），</p><p>最后，您就可以将包发布到 pypi 了。</p><h3 id="准备您的环境" tabindex="-1"><a class="header-anchor" href="#准备您的环境" aria-hidden="true">#</a> 准备您的环境</h3><p>首先，通过<code>pip install -r requirements_dev.txt</code>安装所有必要的开发依赖。</p><h3 id="发版-1" tabindex="-1"><a class="header-anchor" href="#发版-1" aria-hidden="true">#</a> 发版</h3><p>有一个脚本<code>release.sh</code>可以用来执行发版的所有步骤。</p><p>这些步骤包括：</p><ul><li><p>删除所有临时目录（如果存在）</p></li><li><p>（重新）通过 mvn 生成所有必须的源代码</p></li><li><p>运行 linting （flke8）</p></li><li><p>通过 pytest 运行测试</p></li><li><p>Build</p></li><li><p>发布到 pypi</p></li></ul></div><!----><footer class="page-meta"><div class="meta-item edit-link"><a href="https://github.com/apache/iotdb-docs/edit/main/src/zh/UserGuide/Master/API/Programming-Python-Native-API.md" rel="noopener noreferrer" target="_blank" aria-label="发现错误？在 GitHub 上编辑此页" class="nav-link label"><!--[--><svg xmlns="http://www.w3.org/2000/svg" class="icon edit-icon" viewBox="0 0 1024 1024" fill="currentColor" aria-label="edit icon"><path d="M430.818 653.65a60.46 60.46 0 0 1-50.96-93.281l71.69-114.012 7.773-10.365L816.038 80.138A60.46 60.46 0 0 1 859.225 62a60.46 60.46 0 0 1 43.186 18.138l43.186 43.186a60.46 60.46 0 0 1 0 86.373L588.879 565.55l-8.637 8.637-117.466 68.234a60.46 60.46 0 0 1-31.958 11.229z"></path><path d="M728.802 962H252.891A190.883 190.883 0 0 1 62.008 771.98V296.934a190.883 190.883 0 0 1 190.883-192.61h267.754a60.46 60.46 0 0 1 0 120.92H252.891a69.962 69.962 0 0 0-69.098 69.099V771.98a69.962 69.962 0 0 0 69.098 69.098h475.911A69.962 69.962 0 0 0 797.9 771.98V503.363a60.46 60.46 0 1 1 120.922 0V771.98A190.883 190.883 0 0 1 728.802 962z"></path></svg><!--]-->发现错误？在 GitHub 上编辑此页<span><svg class="external-link-icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path><polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg><span class="external-link-icon-sr-only">open in new window</span></span><!----></a></div><div class="meta-item git-info"><div class="update-time"><span class="label">上次编辑于: </span><!----></div><div class="contributors"><span class="label">贡献者: </span><!--[--><!--[--><span class="contributor" title="email: tanxinyu@apache.org">Potato</span><!--]--><!--]--></div></div></footer><!----><!----><!----><!--]--></main><!--]--><footer style="padding-bottom:2rem;"><span id="doc-version" style="display:none;">master</span><p style="text-align:center;color:#909399;font-size:12px;margin:0 30px;">Copyright © 2023 The Apache Software Foundation.<br> Apache and the Apache feather logo are trademarks of The Apache Software Foundation</p><p style="text-align:center;margin-top:10px;color:#909399;font-size:12px;margin:0 30px;"><strong>Have a question?</strong> Connect with us on QQ, WeChat, or Slack. <a href="https://github.com/apache/iotdb/issues/1995">Join the community</a> now.</p><p style="text-align:center;margin-top:10px;color:#909399;font-size:12px;margin:0 30px;"> We use <a href="https://analytics.google.com">Google Analytics</a> to collect anonymous, aggregated usage information. </p></footer></div><!--]--><!--]--><!----><!--]--></div>
    <script type="module" src="/assets/app-601a6ddd.js" defer></script>
  </body>
</html>