import{_ as p,C as o,O as i,P as c,ah as l,Q as s,U as n,ai as t,aW as e}from"./framework-374e0e89.js";const u={},r=e('<h2 id="python-原生接口" tabindex="-1"><a class="header-anchor" href="#python-原生接口" aria-hidden="true">#</a> Python 原生接口</h2><h3 id="依赖" tabindex="-1"><a class="header-anchor" href="#依赖" aria-hidden="true">#</a> 依赖</h3><p>在使用 Python 原生接口包前，您需要安装 thrift (&gt;=0.13) 依赖。</p><h3 id="如何使用-示例" tabindex="-1"><a class="header-anchor" href="#如何使用-示例" aria-hidden="true">#</a> 如何使用 （示例）</h3><p>首先下载最新安装包：<code>pip3 install apache-iotdb</code></p><p><em>注意：如果您想要安装 0.13.0 版本的 Python API，不要使用 <code>pip install apache-iotdb==0.13.0</code>，请使用 <code>pip install apache-iotdb==0.13.0.post1</code> 作为替代！</em></p>',6),d={href:"https://github.com/apache/iotdb/blob/master/client-py/SessionExample.py",target:"_blank",rel:"noopener noreferrer"},k={href:"https://github.com/apache/iotdb/blob/master/client-py/SessionAlignedTimeseriesExample.py",target:"_blank",rel:"noopener noreferrer"},v=e(`<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><h3 id="基本接口说明" tabindex="-1"><a class="header-anchor" href="#基本接口说明" aria-hidden="true">#</a> 基本接口说明</h3><p>下面将给出 Session 对应的接口的简要介绍和对应参数：</p><h4 id="初始化" tabindex="-1"><a class="header-anchor" href="#初始化" aria-hidden="true">#</a> 初始化</h4><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>
</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</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>
</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>开启 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><h4 id="数据定义接口-ddl" tabindex="-1"><a class="header-anchor" href="#数据定义接口-ddl" aria-hidden="true">#</a> 数据定义接口 DDL</h4><h5 id="存储组管理" tabindex="-1"><a class="header-anchor" href="#存储组管理" aria-hidden="true">#</a> 存储组管理</h5><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>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>删除单个或多个存储组</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><h5 id="时间序列管理" tabindex="-1"><a class="header-anchor" href="#时间序列管理" aria-hidden="true">#</a> 时间序列管理</h5><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><h4 id="数据操作接口-dml" tabindex="-1"><a class="header-anchor" href="#数据操作接口-dml" aria-hidden="true">#</a> 数据操作接口 DML</h4><h5 id="数据写入" tabindex="-1"><a class="header-anchor" href="#数据写入" aria-hidden="true">#</a> 数据写入</h5><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>
</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><ul><li>Numpy Tablet</li></ul>`,39),m={href:"https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html",target:"_blank",rel:"noopener noreferrer"},h=e(`<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><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>
  <span class="token string">&quot;root.sg_test_01.d_02&quot;</span><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>
</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></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><h5 id="带有类型推断的写入" tabindex="-1"><a class="header-anchor" href="#带有类型推断的写入" aria-hidden="true">#</a> 带有类型推断的写入</h5><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><h5 id="对齐时间序列的写入" tabindex="-1"><a class="header-anchor" href="#对齐时间序列的写入" aria-hidden="true">#</a> 对齐时间序列的写入</h5><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><h4 id="iotdb-sql-接口" tabindex="-1"><a class="header-anchor" href="#iotdb-sql-接口" aria-hidden="true">#</a> IoTDB-SQL 接口</h4><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><h3 id="对-pandas-的支持" tabindex="-1"><a class="header-anchor" href="#对-pandas-的支持" aria-hidden="true">#</a> 对 Pandas 的支持</h3>`,23),b={href:"https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html",target:"_blank",rel:"noopener noreferrer"},_=e(`<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><h3 id="iotdb-testcontainer" tabindex="-1"><a class="header-anchor" href="#iotdb-testcontainer" aria-hidden="true">#</a> IoTDB Testcontainer</h3>`,4),g=s("code",null,"testcontainers",-1),y={href:"https://testcontainers-python.readthedocs.io/en/latest/index.html",target:"_blank",rel:"noopener noreferrer"},f=e(`<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><h3 id="给开发人员" tabindex="-1"><a class="header-anchor" href="#给开发人员" aria-hidden="true">#</a> 给开发人员</h3><h4 id="介绍" tabindex="-1"><a class="header-anchor" href="#介绍" aria-hidden="true">#</a> 介绍</h4><p>这是一个使用 thrift rpc 接口连接到 IoTDB 的示例。在 Windows 和 Linux 上操作几乎是一样的，但要注意路径分隔符等不同之处。</p><h4 id="依赖-1" tabindex="-1"><a class="header-anchor" href="#依赖-1" aria-hidden="true">#</a> 依赖</h4><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><h4 id="编译-thrift-库并调试" tabindex="-1"><a class="header-anchor" href="#编译-thrift-库并调试" aria-hidden="true">#</a> 编译 thrift 库并调试</h4><p>在 IoTDB 源代码文件夹的根目录下，运行<code>mvn clean generate-sources -pl 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><h4 id="session-客户端-使用示例" tabindex="-1"><a class="header-anchor" href="#session-客户端-使用示例" aria-hidden="true">#</a> Session 客户端 &amp; 使用示例</h4><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><h4 id="测试" tabindex="-1"><a class="header-anchor" href="#测试" aria-hidden="true">#</a> 测试</h4><p>请在<code>tests</code>文件夹中添加自定义测试。</p><p>要运行所有的测试，只需在根目录中运行<code>pytest . </code>即可。</p>`,24),q=s("strong",null,"注意",-1),x={href:"https://testcontainers-python.readthedocs.io/en/latest/index.html",target:"_blank",rel:"noopener noreferrer"},T=s("h4",{id:"其他工具",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#其他工具","aria-hidden":"true"},"#"),n(" 其他工具")],-1),S={href:"https://pypi.org/project/black/",target:"_blank",rel:"noopener noreferrer"},w={href:"https://pypi.org/project/flake8/",target:"_blank",rel:"noopener noreferrer"},D=s("code",null,"black .",-1),I=s("code",null,"flake8 .",-1),N=e('<h4 id="发版" tabindex="-1"><a class="header-anchor" href="#发版" aria-hidden="true">#</a> 发版</h4><p>要进行发版，</p><p>只需确保您生成了正确的 thrift 代码，</p><p>运行了 linting 并进行了自动格式化，</p><p>然后，确保所有测试都正常通过（通过<code>pytest . </code>），</p><p>最后，您就可以将包发布到 pypi 了。</p><h5 id="准备您的环境" tabindex="-1"><a class="header-anchor" href="#准备您的环境" aria-hidden="true">#</a> 准备您的环境</h5><p>首先，通过<code>pip install -r requirements_dev.txt</code>安装所有必要的开发依赖。</p><h5 id="发版-1" tabindex="-1"><a class="header-anchor" href="#发版-1" aria-hidden="true">#</a> 发版</h5><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>',12);function P(E,L){const a=o("ExternalLinkIcon");return i(),c("div",null,[l(`

    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.

`),r,s("p",null,[n("您可以从这里得到一个使用该包进行数据读写的例子："),s("a",d,[n("Session Example"),t(a)])]),s("p",null,[n("关于对齐时间序列读写的例子："),s("a",k,[n("Aligned Timeseries Session Example"),t(a)])]),v,s("p",null,[n("相较于普通 Tablet，Numpy Tablet 使用 "),s("a",m,[n("numpy.ndarray"),t(a)]),n(" 来记录数值型数据。 内存占用和序列化耗时会降低很多，写入效率也会有很大提升。")]),h,s("p",null,[n("我们支持将查询结果轻松地转换为 "),s("a",b,[n("Pandas Dataframe"),t(a)]),n("。")]),_,s("p",null,[n("Python 客户端对测试的支持是基于"),g,n("库 ("),s("a",y,[n("https://testcontainers-python.readthedocs.io/en/latest/index.html"),t(a)]),n(") 的，如果您想使用该特性，就需要将其安装到您的项目中。")]),f,s("p",null,[q,n("一些测试需要在您的系统上使用 docker，因为测试的 IoTDB 实例是使用 "),s("a",x,[n("testcontainers"),t(a)]),n(" 在 docker 容器中启动的。")]),T,s("p",null,[s("a",S,[n("black"),t(a)]),n(" 和 "),s("a",w,[n("flake8"),t(a)]),n(" 分别用于自动格式化和 linting。 它们可以通过 "),D,n(" 或 "),I,n(" 分别运行。")]),N])}const A=p(u,[["render",P],["__file","Programming-Python-Native-API.html.vue"]]);export{A as default};