Search index quick start

Step 1: Create a data table

To create a search index for a data table, you must set the maximum number of versions to 1. You must also set the time to live (TTL) of the data table to -1, which specifies that data never expires, or disable data updates. In this example, the maximum number of versions is set to 1 and the TTL is set to -1.

private static void createTable(
        SyncClient client, String tableName) {
    TableMeta tableMeta = new TableMeta(tableName);
    tableMeta.addPrimaryKeyColumn(
            new PrimaryKeySchema(
                    "product_id", PrimaryKeyType.STRING));

    TableOptions tableOptions = new TableOptions();
    tableOptions.setTimeToLive(-1);
    tableOptions.setMaxVersions(1);

    client.createTable(
            new CreateTableRequest(tableMeta, tableOptions));
}

Step 2: Create a search index

Create index fields for the category and price attribute columns. The name and data type of an index field must be the same as those of the corresponding attribute column in the data table.

private static void createSearchIndex(
        SyncClient client, String tableName, String indexName) {
    IndexSchema indexSchema = new IndexSchema();
    indexSchema.setFieldSchemas(Arrays.asList(
            new FieldSchema("category", FieldType.KEYWORD),
            new FieldSchema("price", FieldType.LONG)));

    CreateSearchIndexRequest request =
            new CreateSearchIndexRequest();
    request.setTableName(tableName);
    request.setIndexName(indexName);
    request.setIndexSchema(indexSchema);
    client.createSearchIndex(request);
}

Search indexes are created asynchronously. Wait until the index status changes to RUNNING and the synchronization phase changes to INCR before you query data.

private static final int RETRY_ATTEMPTS = 90;
private static final long RETRY_INTERVAL_MILLIS = 1_000L;

private static void waitUntilSearchIndexIsReady(
        SyncClient client, String tableName, String indexName)
        throws InterruptedException {
    for (int attempt = 1; attempt <= RETRY_ATTEMPTS; attempt++) {
        DescribeSearchIndexRequest request =
                new DescribeSearchIndexRequest();
        request.setTableName(tableName);
        request.setIndexName(indexName);
        request.setIncludeSyncStat(true);

        DescribeSearchIndexResponse response =
                client.describeSearchIndex(request);
        if (response.getIndexStatus() != null
                && response.getIndexStatus().indexStatusEnum
                == DescribeSearchIndexResponse.IndexStatusEnum.RUNNING
                && response.getSyncStat() != null
                && response.getSyncStat().getSyncPhase()
                == SyncStat.SyncPhase.INCR) {
            return;
        }
        Thread.sleep(RETRY_INTERVAL_MILLIS);
    }
    throw new IllegalStateException(
            "Search index did not become ready before timeout.");
}

Step 3: Write sample data

Write three product rows. The product_id column is the primary key column. The category and price columns are attribute columns.

private static void putSampleRows(
        SyncClient client, String tableName) {
    putProduct(client, tableName, "product-001", "books", 89L);
    putProduct(client, tableName, "product-002", "books", 129L);
    putProduct(client, tableName, "product-003", "devices", 599L);
}

private static void putProduct(
        SyncClient client,
        String tableName,
        String productId,
        String category,
        long price) {
    PrimaryKey primaryKey =
            PrimaryKeyBuilder.createPrimaryKeyBuilder()
                    .addPrimaryKeyColumn(
                            "product_id",
                            PrimaryKeyValue.fromString(productId))
                    .build();

    RowPutChange rowPutChange =
            new RowPutChange(tableName, primaryKey);
    rowPutChange.addColumn(
            "category", ColumnValue.fromString(category));
    rowPutChange.addColumn(
            "price", ColumnValue.fromLong(price));
    client.putRow(new PutRowRequest(rowPutChange));
}

Step 4: Query data

Run a term query to match the rows whose category column value is books. Data synchronization to a search index requires a short period of time. The sample code retries the query if the result is not ready.

private static SearchResponse waitUntilBooksAreQueryable(
        SyncClient client, String tableName, String indexName)
        throws InterruptedException {
    for (int attempt = 1; attempt <= RETRY_ATTEMPTS; attempt++) {
        SearchResponse response =
                queryBooks(client, tableName, indexName);
        if (response.isAllSuccess()
                && response.getTotalCount() == 2L
                && response.getRows().size() == 2) {
            return response;
        }
        Thread.sleep(RETRY_INTERVAL_MILLIS);
    }
    throw new IllegalStateException(
            "Sample rows were not queryable before timeout.");
}

private static SearchResponse queryBooks(
        SyncClient client, String tableName, String indexName) {
    TermQuery termQuery = new TermQuery();
    termQuery.setFieldName("category");
    termQuery.setTerm(ColumnValue.fromString("books"));

    SearchQuery searchQuery = new SearchQuery();
    searchQuery.setQuery(termQuery);
    searchQuery.setLimit(10);
    searchQuery.setTrackTotalCount(
            SearchQuery.TRACK_TOTAL_COUNT);

    SearchRequest.ColumnsToGet columnsToGet =
            new SearchRequest.ColumnsToGet();
    columnsToGet.setReturnAll(true);

    SearchRequest request =
            new SearchRequest(tableName, indexName, searchQuery);
    request.setColumnsToGet(columnsToGet);
    return client.search(request);
}

If both the total number of matched rows and the number of returned rows are 2, the query is successful.