{"id":8254,"date":"2025-08-19T11:23:09","date_gmt":"2025-08-19T18:23:09","guid":{"rendered":"https:\/\/tdengine.com\/?p=8254"},"modified":"2025-08-19T11:23:11","modified_gmt":"2025-08-19T18:23:11","slug":"supertable","status":"publish","type":"post","link":"https:\/\/tdengine.com\/supertable\/","title":{"rendered":"TDengine Innovations: Supertable"},"content":{"rendered":"\n<p>The supertable is a concept introduced by TDengine that enables aggregation operations across tables and makes your <a href=\"https:\/\/tdengine.com\/what-is-a-time-series-database\/\">time-series database<\/a> (TSDB) easier to manage.<\/p>\n\n\n\n<h2 class=\"gb-text\">Introduction<\/h2>\n\n\n\n<p>A supertable is essentially a kind of template that you use to create the tables for your data collection points, known as subtables. Because TDengine TSDB creates one table per data collection point, the total number of tables in a database can become extremely high. By using supertables, you can easily manage the creation of new tables and perform queries across all subtables within a supertable.<\/p>\n\n\n\n<p>In TDengine TSDB, instead of creating tables from scratch, you first create one supertable for each type of data collection point in your environment. Then you create the subtable for each specific data collection point using the template defined by the supertable. Data is not stored in the supertable; it is only a template that defines the schema for its subtables. Queries that you run on the supertable return results for all of the subtables under it.<\/p>\n\n\n\n<p>When you create a supertable, you define metric and tag fields that apply to all subtables under the supertable:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Metrics are the measurements that the data collection point collects &#8212; for example, the temperature in a weather monitoring scenario or the CPU usage in a DevOps scenario.<\/li>\n\n\n\n<li>Tags are static attributes that describe a data collection point &#8212; for example, its location, device manufacturer, or serial number.<br>Note that you can add, remove, and modify tags after a supertable has been created. Your changes take effect on all subtables within the supertable.<\/li>\n<\/ul>\n\n\n\n<p>The subtables in a supertable all have the same data schema, but each has its own specific tag values. The following figure shows an example of a supertable for a smart meters scenario.<\/p>\n\n\n\n<figure class=\"gb-element-66e50afc\">\n<img decoding=\"async\" width=\"1920\" height=\"1159\" class=\"gb-media-ebfd2bdc\" src=\"https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable.png?strip=all&sharp=1\" srcset=\"https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable.png?strip=all&amp;sharp=1 1920w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable-300x181.png?strip=all&amp;sharp=1 300w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable-1024x618.png?strip=all&amp;sharp=1 1024w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable-768x464.png?strip=all&amp;sharp=1 768w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable-1536x927.png?strip=all&amp;sharp=1 1536w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable.png?strip=all&amp;sharp=1&amp;w=384 384w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable.png?strip=all&amp;sharp=1&amp;w=1152 1152w, https:\/\/eujqw4hwudm.exactdn.com\/wp-content\/uploads\/22.060-01-supertable.png?strip=all&amp;sharp=1&amp;w=450 450w\" sizes=\"(max-width: 1200px) 100vw, 1200px\" \/>\n<\/figure>\n\n\n\n<p>In the figure, the supertable <code class=\"\" data-line=\"\">meters<\/code> was created with four metric fields (timestamp, current, voltage, and phase) &#8211; and two tag fields (location and groupID). This represents a type of data collection point &#8211; in this case, a smart meter. Under the <code class=\"\" data-line=\"\">meters<\/code> supertable, three subtables have been created: <code class=\"\" data-line=\"\">d1001<\/code>, <code class=\"\" data-line=\"\">d1002<\/code>, and <code class=\"\" data-line=\"\">d1004<\/code>. Each subtable represents a specific smart meter. <\/p>\n\n\n\n<p>You can query the supertable using tag values as filtering conditions &#8211; for example, in the supertable shown in the figure, you could query the average current of all meters whose location is <code class=\"\" data-line=\"\">California.SanFrancisco<\/code>. This provides a significant performance boost because TDengine TSDB can filter out any subtables that do not meet the specified conditions without scanning the data in those tables.<\/p>\n\n\n\n<h2 class=\"gb-text\">Supertable SQL Statements<\/h2>\n\n\n\n<p>TDengine TSDB supports standard SQL with extensions for time-series applications. You can create, delete, and modify your supertables with SQL statements. For example, the following statement creates the <code class=\"\" data-line=\"\">meters<\/code> supertable shown in the preceding figure:<\/p>\n\n\n\n<pre class=\"wp-block-prismatic-blocks\"><code class=\"language-sql\" data-line=\"\">CREATE STABLE meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (location BINARY(64), groupId INT);<\/code><\/pre>\n\n\n\n<p>In this statement, <code class=\"\" data-line=\"\">CREATE STABLE meters<\/code> creates a supertable named <code class=\"\" data-line=\"\">meters<\/code>. The following parameter defines its metric fields &#8211; a column named <code class=\"\" data-line=\"\">ts<\/code> of type <code class=\"\" data-line=\"\">TIMESTAMP<\/code>, a column named <code class=\"\" data-line=\"\">current<\/code> of type <code class=\"\" data-line=\"\">FLOAT<\/code>, a column named <code class=\"\" data-line=\"\">voltage<\/code> of type <code class=\"\" data-line=\"\">INT<\/code>, and a column named <code class=\"\" data-line=\"\">phase<\/code> of type <code class=\"\" data-line=\"\">FLOAT<\/code>. The <code class=\"\" data-line=\"\">TAGS<\/code> keyword defines the tag fields for the supertable &#8211; in this case a column named <code class=\"\" data-line=\"\">location<\/code> of type <code class=\"\" data-line=\"\">BINARY<\/code> (with a maximum length of 64 bits) and a column named <code class=\"\" data-line=\"\">groupId<\/code> of type <code class=\"\" data-line=\"\">INT<\/code>.<\/p>\n\n\n\n<p>Note that the first column of every table in TDengine TSDB must use the <code class=\"\" data-line=\"\">TIMESTAMP<\/code> data type. TDengine TSDB uses this column as the primary key. For more information about the data types that TDengine TSDB supports, see <a href=\"https:\/\/docs.tdengine.com\/tdengine-reference\/sql-manual\/data-types\/\">Data Types<\/a>.<\/p>\n\n\n\n<p>Now that you have created a supertable, you can use the supertable to create the subtables for your data collection points. For example, the following statement created the <code class=\"\" data-line=\"\">d1001<\/code> subtable shown under <code class=\"\" data-line=\"\">meters<\/code> in the preceding figure.<\/p>\n\n\n\n<pre class=\"wp-block-prismatic-blocks\"><code class=\"language-sql\" data-line=\"\">CREATE TABLE d1001 USING meters TAGS (&quot;California.SanFrancisco&quot;,2);<\/code><\/pre>\n\n\n\n<p>In this statement, the <code class=\"\" data-line=\"\">USING<\/code> keyword specifies a supertable to use as a template for the newly created table &#8212; in this case, the <code class=\"\" data-line=\"\">meters<\/code> supertable. The <code class=\"\" data-line=\"\">TAGS<\/code> keyword specifies the value of each tag field for the subtable. As the <code class=\"\" data-line=\"\">meters<\/code> supertable contains two tag fields &#8211; <code class=\"\" data-line=\"\">location<\/code> and <code class=\"\" data-line=\"\">groupId<\/code> &#8211; this <code class=\"\" data-line=\"\">CREATE TABLE<\/code> statement indicates that the location of the data collection point <code class=\"\" data-line=\"\">d1001<\/code> is <code class=\"\" data-line=\"\">California.SanFrancisco<\/code> and the group ID is <code class=\"\" data-line=\"\">2<\/code>. When you execute this statement, the subtable is created with the same data schema &#8211; four metric columns and two tag columns &#8211; defined in the supertable.<\/p>\n\n\n\n<p>With each of your data collection points storing data in a separate subtable contained within the same supertable, you can easily perform all kinds of queries on your data. You can filter by tag to obtain exactly the results you need without experiencing any performance deterioration.<\/p>\n\n\n\n<p>For technical information about supertables, see <a href=\"https:\/\/docs.tdengine.com\/tdengine-reference\/sql-manual\/manage-supertables\/\">Supertable<\/a> in the TDengine TSDB documentation.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The supertable is a concept introduced by TDengine that enables aggregation operations across tables and makes your time-series database easier to manage.<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"content-type":"","footnotes":""},"categories":[248],"tags":[],"ppma_author":[120],"class_list":["post-8254","post","type-post","status-publish","format-standard","hentry","category-time-series-database"],"authors":[{"term_id":120,"user_id":2,"is_guest":0,"slug":"jianhui-tao","display_name":"Jeff Tao","avatar_url":{"url":"https:\/\/tdengine.com\/wp-content\/uploads\/29.04-15-jhtao.jpg","url2x":"https:\/\/tdengine.com\/wp-content\/uploads\/29.04-15-jhtao.jpg"},"1":"","2":"","3":"","4":"","5":"","6":"","7":"","8":""}],"_links":{"self":[{"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/posts\/8254","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/comments?post=8254"}],"version-history":[{"count":8,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/posts\/8254\/revisions"}],"predecessor-version":[{"id":27891,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/posts\/8254\/revisions\/27891"}],"wp:attachment":[{"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/media?parent=8254"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/categories?post=8254"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/tags?post=8254"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/tdengine.com\/wp-json\/wp\/v2\/ppma_author?post=8254"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}