This topic describes how to use the multi-value model to write data. For more information, see Aliyun TSDB SDK for Java. You can download the required code from the website and view examples that are provided in the test/example/ExampleOfMultiField and test/com.aliyun.hitsdb.client/TestHiTSDBClientMultiFieldFeatures directories.

Note: Only the Lindorm SDK V0.2.0 or later supports the multi-value model. For more information about the latest SDK version and download link, see the "Versions" section in the SDK documentation. SDKs that are earlier than V0.2.0 use a simulated multi-value model. We recommend that you do not use the simulated multi-value model. You cannot use the multi-value model-related MultiField class of the latest SDK to query the written data by using the MultiValue class of an earlier SDK version.

Use the multi-value model to write data

Sample code:

        /*
         * Use the multiFieldPutSync() function.
         * This function supports single-point or multi-point writes.
         *
         * The following information is required when you write data:
         * Metric: the category of a metric. Metrics are similar to the measurements of InfluxDB.
         * Fields: the measurement information of a metric. Each field specifies a sub-category of a metric. A metric can contain multiple fields. For example, a metric is named wind. This metric contains the following fields: direction, speed, direction, description, and temperature.
         * Timestamp: the timestamp of a point.
         * Tags: the extra information of a timeline, for example, a model of ABC123 and a manufacturer part number of 1234567890.
         */
        MultiFieldPoint multiFieldPoint = MultiFieldPoint.metric("wind")
                .field("speed", 45.2)
                .field("level", 1.2)
                .field("direction", "S")
                .field("description", "Breeze")
                .tag("sensor", "95D8-7913")
                .tag("city", "hangzhou")
                .tag("province", "zhejiang")
                .timestamp(1537170208L)
                .build();

        // Synchronous writes.
        tsdb.multiFieldPutSync(multiFieldPoint);

Use the multi-value model to perform asynchronous writes

Note: Only the Lindorm SDK V0.2.1 or later versions support this feature. For more information about the latest SDK version and download link, see the "Versions" section in the SDK documentation.

Do not use a callback function

By default, no callback function is specified in the TSDBConfig class to perform asynchronous multi-value writes. Sample code:
TSDBConfig config = TSDBConfig.address("127.0.0.1", 8242)
                // The volume of data that is submitted each time that a batch write operation is performed.
                .batchPutSize(500)
                // The number of threads that are used to process asynchronous single-value writes.
                .batchPutConsumerThreadCount(1)
                // The length of the cache queue in which asynchronous multi-value writes are sequenced.
                .multiFieldBatchPutBufferSize(10000)
                // The number of threads that are used to process asynchronous multi-value writes.
                .multiFieldBatchPutConsumerThreadCount(1)
                .config();

        // Note: You need to initiate a TSDB instance only once.
        TSDB tsdb = TSDBClientFactory.connect(config);

        MultiFieldPoint point = MultiFieldPoint
                .metric("test-test-test")
                .tag("a", "1")
                .tag("b", "2")
                .timestamp(System.currentTimeMillis())
                .field("f1", Math.random())
                .field("f2", Math.random())
                .build();
        tsdb.multiFieldPut(point);

        // Note: During the lifecycle of an application, you do not need to close the specified TSDB instance until the application ends.
        tsdb.close();
    }

Use a common callback function

A common callback function returns only the data points of a successful write operation, or the data points of a failed write operation and the related write exceptions. Sample code:
      // Creates a common callback function to process successful or failed writes.
      AbstractMultiFieldBatchPutCallback callback = new MultiFieldBatchPutCallback() {

            @Override
            public void response(String address, List<MultiFieldPoint> points, Result result) {
                int count = num.addAndGet(points.size());
                System.out.println(result);
                System.out.println("The system has processed" + count + "points.");
            }
            final AtomicInteger num = new AtomicInteger();
            @Override
            public void failed(String address, List<MultiFieldPoint> points, Exception ex) {
                System.err.println("The callback function fails." + points.size() + " error!");
                ex.printStackTrace();
            }
        };

       TSDBConfig config = TSDBConfig.address("127.0.0.1", 8242)
                .httpConnectTimeout(90)
                // The volume of data that is submitted each time that a batch write operation is performed.
                .batchPutSize(500)
                // The number of threads that are used to process asynchronous single-value writes.
                .batchPutConsumerThreadCount(1)
                // The length of the cache queue in which asynchronous multi-value writes line up.
                .multiFieldBatchPutBufferSize(10000)
                // The number of threads that are used to process asynchronous multi-value writes.
                .multiFieldBatchPutConsumerThreadCount(1)
                // The callback function that is used to obtain the results of asynchronous multi-value writes.
                .listenMultiFieldBatchPut(callback)
                .config();

        // Note: You need to initiate a TSDB instance only once.
        TSDB tsdb = TSDBClientFactory.connect(config);

        MultiFieldPoint point = MultiFieldPoint
                .metric("test-test-test")
                .tag("a", "1")
                .tag("b", "2")
                .timestamp(System.currentTimeMillis())
                .field("f1", Math.random())
                .field("f2", Math.random())
                .build();
        tsdb.multiFieldPut(point);

        // Note: During the lifecycle of an application, you do not need to close the specified TSDB instance until the application ends.
        tsdb.close();
    }

Use a summary callback function

If a write operation succeeds, the summary callback function returns the data points of the write operation and the related summary information. The information includes the number of successful points and the number of failed points. If a write operation fails, the summary callback function returns the data points of the write operation and the related write exceptions. Sample code:
      // Creates a summary callback function to process successful writes or failed writes.
      AbstractMultiFieldBatchPutCallback callback = new MultiFieldBatchPutSummaryCallback() {

            final AtomicInteger num = new AtomicInteger();
            @Override
            public void response(String address, List<MultiFieldPoint> points, SummaryResult result) {
                int count = num.addAndGet(points.size());
                System.out.println(result);
                System.out.println("The system has processed" + count + "points.");
            }



            @Override
            public void failed(String address, List<MultiFieldPoint> points, Exception ex) {
                System.err.println("The callback function fails" + points.size() + " error!");
                ex.printStackTrace();
            }
        };

       TSDBConfig config = TSDBConfig.address("127.0.0.1", 8242)
                .httpConnectTimeout(90)
                // The volume of data that is submitted each time that a batch write operation is performed.
                .batchPutSize(500)
                // The number of threads that are used to process asynchronous single-value writes.
                .batchPutConsumerThreadCount(1)
                // The length of the cache queue in which asynchronous multi-value writes are sequenced.
                .multiFieldBatchPutBufferSize(10000)
                // The number of threads that are used to process asynchronous multi-value writes.
                .multiFieldBatchPutConsumerThreadCount(1)
                // The callback function that is used to obtain the results of asynchronous multi-value writes.
                .listenMultiFieldBatchPut(callback)
                .config();

        // Note: You need to initiate a TSDB instance only once.
        TSDB tsdb = TSDBClientFactory.connect(config);

        MultiFieldPoint point = MultiFieldPoint
                .metric("test-test-test")
                .tag("a", "1")
                .tag("b", "2")
                .timestamp(System.currentTimeMillis())
                .field("f1", Math.random())
                .field("f2", Math.random())
                .build();
        tsdb.multiFieldPut(point);

        // Note: During the lifecycle of an application, you do not need to close the specified TSDB instance until the application ends.
        tsdb.close();
    }

Use a detail callback function

If a write operation succeeds, the detail callback function returns the data points and details of the write operation. The details include failed points and the related errors. If a write operation fails, the detail callback function returns the data points of the write operation and the related write exceptions. Sample code:
      // Creates a detail callback function to process successful writes or failed writes.
      MultiFieldBatchPutDetailsCallback callback = new MultiFieldBatchPutDetailsCallback() {

            final AtomicInteger num = new AtomicInteger();

            @Override
            public void response(String address, List<MultiFieldPoint> points, DetailsResult result) {
                int count = num.addAndGet(points.size());
                System.out.println(result);
                System.out.println(The system has processed" + count + "points.");
            }

            @Override
            public void failed(String address, List<MultiFieldPoint> points, Exception ex) {
                System.err.println("The callback function fails." + points.size() + " error!");
                ex.printStackTrace();
            }
        };

       TSDBConfig config = TSDBConfig.address("127.0.0.1", 8242)
                .httpConnectTimeout(90)
                // The volume of data that is submitted each time that a batch write operation is performed.
                .batchPutSize(500)
                // The number of threads that are used to process asynchronous single-value writes.
                .batchPutConsumerThreadCount(1)
                // The length of the cache queue in which asynchronous multi-value writes are sequenced.
                .multiFieldBatchPutBufferSize(10000)
                // The number of threads that are used to process asynchronous multi-value writes.
                .multiFieldBatchPutConsumerThreadCount(1)
                // The callback function that is used to obtain the results of asynchronous multi-value writes.
                .listenMultiFieldBatchPut(callback)
                .config();

        // Note: You need to initiate a TSDB instance only once.
        TSDB tsdb = TSDBClientFactory.connect(config);

        MultiFieldPoint point = MultiFieldPoint
                .metric("test-test-test")
                .tag("a", "1")
                .tag("b", "2")
                .timestamp(System.currentTimeMillis())
                .field("f1", Math.random())
                .field("f2", Math.random())
                .build();
        tsdb.multiFieldPut(point);

        // Note: During the lifecycle of an application, you do not need to close the specified TSDB instance until the application ends.
        tsdb.close();
    }