{"id":19974005,"url":"https://github.com/objectbox/objectbox-ts-demo","last_synced_at":"2025-05-04T02:32:24.572Z","repository":{"id":62371429,"uuid":"276065506","full_name":"objectbox/objectbox-ts-demo","owner":"objectbox","description":"Time Series example project for ObjectBox TS","archived":false,"fork":false,"pushed_at":"2024-10-16T11:29:00.000Z","size":596,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T01:42:32.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/objectbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-30T10:15:28.000Z","updated_at":"2024-10-16T11:29:04.000Z","dependencies_parsed_at":"2024-07-17T09:18:44.597Z","dependency_job_id":"d7f5e942-cc64-48d6-bf15-816d4dad33ad","html_url":"https://github.com/objectbox/objectbox-ts-demo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectbox%2Fobjectbox-ts-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectbox%2Fobjectbox-ts-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectbox%2Fobjectbox-ts-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectbox%2Fobjectbox-ts-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/objectbox","download_url":"https://codeload.github.com/objectbox/objectbox-ts-demo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252279049,"owners_count":21722827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T03:13:34.829Z","updated_at":"2025-05-04T02:32:24.274Z","avatar_url":"https://github.com/objectbox.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"ObjectBox TS (Time Series) Demo\n===============================\n**ObjectBox TS** offers additional time series functionality over the standard ObjectBox database.\nThis allows very efficient processing of time based data, while still offering object based persistence.\n\nThis demo shows [how to develop with ObjectBox TS using C++](https://cpp.objectbox.io/time-series-data) (contact us for other languages).\nWhile its usage is very similar to standard ObjectBox, it comes with superior performance for time based data.\n\nRun the TS Demo\n---------------\n**In order to run this demo, you need to get the [ObjectBox TS library from objectbox.io](https://objectbox.io/time-series-database/).**\nThe [CMake build build](CMakeLists.txt) expects the library (e.g. libobjectbox.so) in `lib/` in the project directory.\n\nIf you do not have the TS library yet, you can still build the project with the standard (non-TS) ObjectBox library.\n\nAt this point you should be able to run the demo in a CMake aware IDE.\nOr, if you prefer the command line, run these commands to build and run the demo:\n\n    cmake .\n    make\n    ./objectbox_ts_demo\n\nTime Series data type\n---------------------\nThis example stores data from sensors at a specific time in a type called `SensorValues`.\nThis type is defined in the file [ts-data-model.fbs](ts-data-model.fbs) like this:\n\n```\ntable SensorValues {\n    id: ulong;\n\n    /// objectbox:id-companion,date\n    time: long;\n\n    temperatureOutside: double;\n    temperatureInside: double;\n    // ...\n}\n```\n\nPlease pay special attention to the `time` property and that it is annotated by `/// objectbox:id-companion,date`.\nThis specific annotation makes `SensorValues` a TS type and thus enables time series functionality for it.\n\nAnd by the way, the mentioned .fbs file is a FlatBuffers schema definition,\nwhich is also used by [ObjectBox Generator](https://github.com/objectbox/objectbox-generator).\nThe latter generates the `SensorValues` C++ struct and binding code to enable `obx::Box\u003cSensorValues\u003e`.   \n \nStoring Time Series data\n------------------------\nAll (non-generated) source code is contained in the [main.cpp](src/main.cpp) file.\nAs you will see, storing time series data is no different from storing other object data.\nUsing a templated `obx::Box`, it's a single call to `put()`:\n\n    std::vector\u003cSensorValues\u003e values = createSensorValueData(now, dataCount);\n    boxSV.put(values);\n\nNote that `createSensorValueData()` creates dummy sensor data, which is mostly unrelated to ObjectBox.\nThe single special thing here is that the `SensorValues.id` member is set to `OBX_ID_NEW` to mark it as an new object.\n\nGet the minimum and maximum time values\n---------------------------------------\nOften, you want to know the minimum and/or maximum time values of the stored data.\nFor ObjectBox TS, this is a very efficient look up.  \nIn the [main.cpp](src/main.cpp) file, you will find an example in the `printMinMaxTime()` function:\n\n    int64_t timeMin{0}, timeMax{0};\n    box.timeSeriesMinMax(nullptr, \u0026timeMin, nullptr, \u0026timeMax);\n\nThere's also an overload of `timeSeriesMinMax()` accepting a time range (begin and end time) within to look for min/max values.\n\nQuerying Time Series data\n-------------------------\nTS enabled types can accessed just like other types.\nFor example, `obx::Box::get(id)` returns an object for the given ID.\nQueries also work as usual. With one pleasant exception: time based queries perform much faster.\nThe runtime behavior of queries using time series properties is similar to queries using indexed properties,\nbut without requiring extra storage for index data.\nThus, TS queries scale very well with a high number of objects because they avoid scanning all objects.  \n\nIn [main.cpp](src/main.cpp), there's a function `buildAndRunQueries()`, which shows two queries in action.\nUsing the standard query builder approach, we add a \"between\" condition on the `time` property associated with \"SensorValues\".\nIt queries for `SensorValues` in the time range from \"1 second since start\" until \"2 seconds since start\":    \n\n    obx::QueryBuilder\u003cSensorValues\u003e qbRange = box.query();\n    obx_qb_int_between(qbRange.cPtr(), SensorValues_::time, start + 1000, start + 1999);\n    obx::Query\u003cSensorValues\u003e query = qbRange.build();\n    std::vector\u003cstd::unique_ptr\u003cSensorValues\u003e\u003e result = query.find();\n    \n### Query with time links\n\nThe second query also returns object in a time range.\nBut instead of specifying the time range directly, we want to refer to a time range defined in another type.\nLet's have another look at [ts-data-model.fbs](ts-data-model.fbs) to locate the `NamedTimeRange` type:\n\n```\ntable NamedTimeRange {\n    id: ulong;\n\n    /// objectbox:date\n    begin: long;\n\n    /// objectbox:date\n    end: long;\n\n    name: string;\n}\n```\n\nThis type is an example for how to dynamically define time ranges.\nIn the function `putAndPrintNamedTimeRanges()`, we put two time ranges into the database.\nOne called \"green\" and the other called \"red\".\n\nSo now let's query for all `SensorValues` objects that fall in the time range of the `NamedTimeRange` instance called \"green\".\nTo do so, we need to define a \"link\" between these two types.\nAs this link is time based, we need to tell ObjectBox which properties define the time range (begin and end time).\n\n    obx::QueryBuilder\u003cSensorValues\u003e qbLink = box.query();\n    obx::QueryBuilder\u003cNamedTimeRange\u003e qbNamedTimeRange =\n        qbLink.linkTime\u003cNamedTimeRange\u003e(NamedTimeRange_::entityId(), NamedTimeRange_::begin, NamedTimeRange_::end);\n    obx_qb_string_equal(qbNamedTimeRange.cPtr(), NamedTimeRange_::name, \"green\", true);\n\nNote, that the result of linking to `NamedTimeRange` results in a `QueryBuilder\u003cNamedTimeRange\u003e`.\nThus, the scope of that query builder is `NamedTimeRange` and we can define query criteria for `NamedTimeRange`.\nThis is what we do in the last line (`obx_qb_string_equal()`) to match against the \"green\" time range.\n\nNext steps\n----------\nThis example project showed how to get started with ObjectBox TS and its very efficient time series functionality. \nWant more? Just reach out to us using the [ObjectBox TS web page](https://objectbox.io/time-series-database/).\nWe're happy to learn about your individual use case and how ObjectBox TS can help you. \n\n### Object Browser TS\n\nPlease contact us if you are interested in the time series enabled data object browser.\nHere are some screenshots to give you a first impression:\n\n![ObjectBox Browser TS ](images/objectbox-ts-browser.png \"\")\n\n![ObjectBox Browser TS ](images/objectbox-ts-browser-graph.png \"\")\n\nLicense\n-------\n    Copyright 2021-2024 ObjectBox Ltd. All rights reserved.\n    \n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n    \n        http://www.apache.org/licenses/LICENSE-2.0\n    \n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobjectbox%2Fobjectbox-ts-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobjectbox%2Fobjectbox-ts-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobjectbox%2Fobjectbox-ts-demo/lists"}