Initialize TsFile extras documentation
diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..1c4971b --- /dev/null +++ b/.editorconfig
@@ -0,0 +1,35 @@ +# 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. + +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[*.py] +indent_size = 4 + +[Makefile] +indent_style = tab
diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b98686e --- /dev/null +++ b/.gitignore
@@ -0,0 +1,74 @@ +# 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. + +# OS and editor state +.DS_Store +Thumbs.db +.idea/ +.vscode/ +*.iml +*.swp +*.swo +*~ + +# Local credentials and developer-only installations +.env +.env.* +!.env.example +!.env.*.example +.local/ +/downloads/ +/artifacts/ + +# Out-of-tree builds and generated distribution output +build/ +build-*/ +cmake-build-*/ +CMakeFiles/ +CMakeCache.txt +cmake_install.cmake +CTestTestfile.cmake +Testing/ +compile_commands.json +dist/ +target/ + +# Compiled native artifacts +*.o +*.obj +*.a +*.lib +*.so +*.so.* +*.dylib +*.dll +*.exe +*.pdb +*.duckdb_extension + +# Python helper environments and caches +.venv/ +venv/ +__pycache__/ +*.py[cod] +.pytest_cache/ + +# Runtime logs (keep generated datasets inside ignored build directories) +*.log + +# Intentionally do not blanket-ignore *.tsfile, *.db, or *.sqlite: +# documented fixtures may be tracked.
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cad4068 --- /dev/null +++ b/AGENTS.md
@@ -0,0 +1,70 @@ +<!-- + +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. + +--> + +# Repository guidance + +## Purpose + +Apache TsFile Extras maintains integrations between TsFile and external systems. +Read `README.md`, `docs/architecture.md`, and the affected module's README before +making changes. Keep `README.md` and `README-zh.md` consistent. + +## Module boundaries + +- Organize integrations by external system: `sqlite/` and `duckdb/`. +- Keep module-specific code, builds, tests, examples, and guides together. +- Use the installed TsFile SDK. CMake consumers use + `find_package(TsFile CONFIG REQUIRED)` and `TsFile::tsfile`; pkg-config uses + `libtsfile`. Respect the integration's shared or static linkage requirements. +- Do not vendor TsFile core sources, require a sibling checkout, or introduce a + default network fetch. A locally built SDK must be installed into a prefix. +- Do not treat every installed header as a stable public API. Document any + dependency on internal interfaces. +- Do not add CI, root aggregate builds, dependency installers, or publication + automation unless requested. Do not change external registry entries as + incidental cleanup. + +## Documentation + +Describe the repository's purpose and the integrations' functionality directly. +Keep project descriptions free of task status, scaffolding notes, migration +checklists, and setup history. Link to source and usage guides without implying +that external code is present locally. Do not claim unverified compatibility. + +Do not embed machine-specific paths or private documents in public instructions. +Use public references and configurable SDK prefixes. + +## Validation + +Check local links, whitespace, license headers, and ignore rules for documentation +changes. For implementation changes, use the module's documented build and test +commands and report what was actually run. + +Do not commit binaries, SDK packages, secrets, or large datasets. Do not +blanket-ignore intentional `.tsfile` or database fixtures. + +## License and Git + +Use Apache License 2.0 headers on source, configuration, and Markdown files. Keep +`LICENSE` and `NOTICE` in their standard standalone formats and preserve +attribution for imported material. + +Do not add a `Co-Authored-By` trailer. Do not commit or push unless requested.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ddda7b5 --- /dev/null +++ b/CONTRIBUTING.md
@@ -0,0 +1,63 @@ +<!-- + +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. + +--> + +# Contributing + +Keep changes focused on the affected integration. Read its documentation and the +[SDK dependency requirements](docs/dependencies.md) before changing the build or +adding dependencies. + +## Code and documentation + +- Keep implementation, tests, examples, and usage documentation in the module for + the external system. +- Use an installed TsFile SDK rather than a copy of the core source tree. +- Follow the integration's build and formatting conventions. Record the commands + run, dependency versions, and test results with a change. +- Keep the English and Chinese root READMEs consistent. Document supported + behavior and limitations without overstating compatibility. +- When adding an integration, follow [Adding an integration](docs/adding-integration.md). + +## Importing code + +Record the source repository and exact commit. Preserve attribution and relevant +history, documentation, and tests. Review the license and notice requirements of +the files being imported; do not copy notices for unrelated components. + +Replace dependencies on the TsFile source-tree layout with the installed SDK +interface. Document any remaining use of internal APIs. Keep changes to external +distribution systems, such as the DuckDB community registry, separate from source +imports. + +## Files and formatting + +Use UTF-8, LF line endings, and a final newline. Follow `.editorconfig`. + +New source, configuration, and Markdown files require the Apache License 2.0 +header in the appropriate comment syntax. Keep `LICENSE` and `NOTICE` in their +standard standalone formats and preserve third-party attribution. + +Do not commit SDK installations, build outputs, credentials, or large generated +datasets. Small test fixtures may be included with their provenance and purpose. + +## Commits + +Use focused commits describing the change. Do not add a `Co-Authored-By` trailer.
diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/LICENSE
@@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed 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.
diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..ca4b84f --- /dev/null +++ b/NOTICE
@@ -0,0 +1,5 @@ +Apache TsFile Extras +Copyright 2026 The Apache Software Foundation. + +This product includes software developed at +The Apache Software Foundation (http://www.apache.org/).
diff --git a/README-zh.md b/README-zh.md new file mode 100644 index 0000000..f521c04 --- /dev/null +++ b/README-zh.md
@@ -0,0 +1,45 @@ +<!-- + +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. + +--> + +# Apache TsFile Extras + +[English](README.md) + +Apache TsFile Extras 用于维护 [Apache TsFile](https://github.com/apache/tsfile) +与外部系统的集成方案，包括适配代码、使用文档和示例。 +通过这些集成，应用可以在其他系统中读写 TsFile，并结合各系统的存储和查询能力使用时序数据。 + +## 集成 + +| 系统 | 功能 | +| --- | --- | +| [SQLite](sqlite/README.md) | 使用 SQLite 管理可修改的数据，使用 TsFile 压缩存储历史数据，通过同一逻辑表进行 SQL 查询。 | +| [DuckDB](duckdb/README.md) | 使用 DuckDB SQL 查询 TsFile，并将查询结果导出为 TsFile。 | + +## 开发 + +各集成按外部系统组织，复用已安装的 TsFile SDK。 +构建要求和使用方法见对应集成的文档；SDK 配置方式见 +[依赖说明](docs/dependencies.md)，贡献要求见 [贡献指南](CONTRIBUTING.md)。 + +## 许可证 + +本项目采用 [Apache License 2.0](LICENSE)，归属说明见 [NOTICE](NOTICE)。
diff --git a/README.md b/README.md new file mode 100644 index 0000000..f1b1677 --- /dev/null +++ b/README.md
@@ -0,0 +1,48 @@ +<!-- + +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. + +--> + +# Apache TsFile Extras + +[中文](README-zh.md) + +Apache TsFile Extras brings together integrations between +[Apache TsFile](https://github.com/apache/tsfile) and external systems, including +adapters, usage guides, and examples. These integrations let applications read +and write TsFile through other systems and combine TsFile with their storage +and query capabilities. + +## Integrations + +| Integration | Description | +| --- | --- | +| [SQLite](sqlite/README.md) | Combine SQLite's mutable data with compressed historical data in TsFile, with SQL access through a single logical table. | +| [DuckDB](duckdb/README.md) | Query TsFile with DuckDB SQL and export query results to TsFile. | + +## Development + +Integrations are organized by external system and use the installed TsFile SDK. +Build requirements and usage instructions are documented by each integration. +See [SDK dependencies](docs/dependencies.md) for SDK configuration and +[CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. + +## License + +[Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE) for attribution.
diff --git a/docs/adding-integration.md b/docs/adding-integration.md new file mode 100644 index 0000000..788b7c5 --- /dev/null +++ b/docs/adding-integration.md
@@ -0,0 +1,60 @@ +<!-- + +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. + +--> + +# Adding an integration + +Create a top-level directory named after the external system, using a concise +lowercase name. Keep code for the same integration together even when it uses +more than one programming language. + +## Documentation + +The module README should describe: + +- What the integration does and its main use cases. +- Prerequisites, installation, and build instructions. +- A minimal usage example and links to detailed documentation. +- Supported versions and platforms, with known limitations. +- Source code and instructions for running tests. + +Link to external implementations and guides where appropriate. Add the module to +both root READMEs. Write for users and contributors; keep setup history and task +progress out of project descriptions. + +## Implementation + +Keep source, tests, examples, and documentation within the module. Preserve a +useful upstream layout rather than imposing a common directory structure on +unrelated build systems. Add directories and build files with the content they +support. + +Use the [installed TsFile SDK](dependencies.md). Document host-specific linkage +and runtime deployment requirements. General-purpose TsFile functionality belongs +in the core project. + +## Source and test data + +When importing code, record the original repository and commit, and preserve its +license and attribution. Include relevant tests and documentation. + +Prefer small generated examples or documented fixtures. Do not commit SDK +archives, compiled extensions, private data, or large datasets. Small TsFile and +database fixtures may be tracked when needed by tests.
diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..ed9b1d7 --- /dev/null +++ b/docs/architecture.md
@@ -0,0 +1,60 @@ +<!-- + +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. + +--> + +# Architecture + +TsFile Extras organizes integrations by external system. Each module owns its +adapter, build configuration, documentation, examples, and tests. + +## Project boundaries + +TsFile core owns the file format, encoding, compression, general-purpose APIs, +and SDK packaging. Extras owns the code that connects those APIs to external +systems. General-purpose changes belong in the core project rather than a +private copy of TsFile inside an integration. + +## Modules + +- **SQLite:** the SQLite extension, including logical tables, sealing, and export. +- **DuckDB:** the DuckDB extension, SQL interface, and host-specific packaging. + +Modules have independent build requirements. Working on one integration should +not require installing the other systems. Shared build helpers should be added +only when multiple modules need them. + +## Dependencies + +Integrations consume an installed TsFile SDK, including SDKs built locally and +installed into a separate prefix. They must not depend on the location of a +TsFile source or build tree. See [SDK dependencies](dependencies.md). + +Static or shared linkage is selected per integration according to the host's +runtime and distribution requirements. + +## Compatibility + +Document the TsFile SDK version, host version, platform, architecture, and linkage +used for each supported configuration. A TsFile package being available for a +platform does not by itself establish compatibility with an integration. + +Keep host-specific installation and distribution requirements with the module. +Changes to external registries should be reviewed separately from changes to +adapter code.
diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..5abc0c0 --- /dev/null +++ b/docs/dependencies.md
@@ -0,0 +1,106 @@ +<!-- + +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. + +--> + +# Consuming the TsFile SDK + +## Use an installation, not a source checkout + +Native integrations should depend on an installed TsFile SDK. Use the +installation instructions for the TsFile package and platform you select. Do not +add a second TsFile installer, vendor the core library, or automatically download +and build a floating branch from an extras module. + +The established packaging contract provides a library, development headers, +CMake package configuration, and pkg-config metadata beneath an installation +prefix. The following references describe the SDK at commit `6f38c703962a`: + +- [TsFile packaging documentation](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/packaging/README.md) +- [Installed CMake consumer](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/cpp/cmake/tests/projects/InstalledConsumer/CMakeLists.txt) +- [pkg-config metadata](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/cpp/cmake/libtsfile.pc.in) + +## Selecting installation components + +| Installation family | Development requirements | +| --- | --- | +| APT | Runtime `tsfile` and development package `tsfile-dev`. | +| RPM | Runtime `tsfile` and development package `tsfile-devel`. | +| Homebrew | The installed Formula's prefix, including library and headers; development Formula `tsfile-dev` is keg-only. | +| Windows SDK ZIP | The extracted SDK root containing `bin`, `include`, and `lib`, matching the consumer's architecture and toolchain. | + +`tsfile-tools` supplies the CLI where packaging separates it from the library; +it is not a substitute for development headers and link files. Availability and +installation commands are owned by the TsFile package distribution. Do not infer +support for additional platforms or architectures from this table. + +## CMake and pkg-config + +CMake-based integrations should use `find_package(TsFile CONFIG REQUIRED)` and +link their actual targets to `TsFile::tsfile`. Use `CMAKE_PREFIX_PATH` to select +a non-default SDK installation, or `TsFile_DIR` for the directory containing +`TsFileConfig.cmake`. Consume the exported include paths and dependencies rather +than reconstructing them in a custom `FindTsFile.cmake`. + +For a Homebrew development installation, `brew --prefix tsfile-dev` identifies +the Formula-specific prefix. Do not hard-code `/opt/homebrew` or `/usr/local`. +On Windows, point the consumer at the extracted SDK root, not just its DLL. + +Consumers using pkg-config can query `libtsfile`; configure `PKG_CONFIG_PATH` +when the installation is outside the normal search path. Runtime library +resolution is separate from build-time package discovery and must be documented +by the integration. + +## Shared and static linkage + +Choose linkage according to the host and distribution requirements. An installed +SDK may be shared or static; an existing binary package must not be assumed to +contain both variants. Verify the selected artifact, compiler and runtime ABI, +position-independent code requirements, and transitive dependencies as relevant. + +If the required SDK variant is unavailable as a package, build and install it +into a separate prefix using the upstream instructions, then consume that prefix +normally. Do not silently switch to a network source build during configuration. + +For shared builds, deployment instructions must account for the runtime library. +For static builds, preserve the exported dependency and licensing requirements. + +## Source-based development + +To work with an unpublished core change, the developer builds and installs TsFile +into a chosen prefix outside this repository. Extras then uses that same CMake +or pkg-config interface. SDK source location and build directories are not part +of the integration contract. + +Installed headers include a compatibility closure, not only stable public entry +points. Consult the [public-header definition](https://github.com/apache/tsfile/blob/6f38c703962ab6224b09fc299f94ad42e6af88a1/cpp/cmake/TsFilePublicHeaders.cmake) +and document any dependence on implementation-level interfaces. + +## Version records + +Each implementation should record the following when it is actually exercised: + +- Exact SDK artifact version, source commit when available, and distribution. +- Host system version, operating system, architecture, and relevant toolchain. +- Shared or static linkage and important SDK build options. +- Commands run, results, and known limitations. + +Development snapshots must remain labeled as such; do not describe them as RCs +or formal releases. Pin immutable versions when reproducibility is needed rather +than relying on `latest` or a moving branch.
diff --git a/duckdb/README.md b/duckdb/README.md new file mode 100644 index 0000000..c0008d9 --- /dev/null +++ b/duckdb/README.md
@@ -0,0 +1,39 @@ +<!-- + +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. + +--> + +# DuckDB integration + +The TsFile extension for DuckDB lets applications query TsFile using SQL and +write query results to TsFile. It connects TsFile storage with DuckDB's query +engine without requiring applications to call the TsFile API directly. + +## Features + +- Read TsFile data in DuckDB SQL queries. +- Export data to TsFile with `COPY`. + +## Documentation and source + +See the extension repository for installation instructions, supported versions, +and SQL examples. + +- [Source code and usage guide](https://github.com/TimechoLab/tsfile-duckdb) +- [DuckDB community extension registration](https://github.com/duckdb/community-extensions/blob/c5bcc1142fe43950a32ba43704aad12e1fab28e3/extensions/tsfile/description.yml)
diff --git a/sqlite/README.md b/sqlite/README.md new file mode 100644 index 0000000..860958d --- /dev/null +++ b/sqlite/README.md
@@ -0,0 +1,46 @@ +<!-- + +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. + +--> + +# SQLite integration + +The SQLite integration combines SQLite's transactional storage with TsFile's +compression for historical time-series data. Applications read and write through +a logical table: mutable data stays in SQLite, while sealed data is stored in +TsFile and remains queryable through the same table. + +## Features + +- Create a writable table with a declared schema, or initialize one from an + existing TsFile. +- Seal data into TsFile through SQL. Sealed rows remain readable but cannot be + updated or deleted. +- Query an existing TsFile as a read-only table. +- Export a table to an independent TsFile, including its hot data. + +## Documentation and source + +For build instructions, SQL examples, and transaction semantics, see the user +guides: + +- [English user guide](https://github.com/apache/tsfile/blob/experiment-sqlite/cpp/src/sqlite/USER_GUIDE_EN.md) +- [中文使用手册](https://github.com/apache/tsfile/blob/experiment-sqlite/cpp/src/sqlite/USER_GUIDE.md) +- [Source code](https://github.com/apache/tsfile/tree/experiment-sqlite/cpp/src/sqlite) +- [Mailing-list discussion](https://lists.apache.org/thread/62oqkfo2nmojhrhfnrb1rhhwn4vcykw6)