Build an IM system

Step 1: Initialize Timeline and create data tables

Initialize a TimelineV2 object and configure the table schema and indexes for the store library, sync library, and meta library. The search index on the store library enables full-text message search, and the search index on the meta library enables group name search.

// Initialize Timeline SDK with three libraries: meta, store, and sync
TimelineStoreFactory serviceFactory = new TimelineStoreFactoryImpl(syncClient);

// Timeline identifier schema (shared by all three libraries)
TimelineIdentifierSchema idSchema = new TimelineIdentifierSchema.Builder()
        .addStringField("timeline_id").build();

// Meta library: stores conversation metadata with search index for group name search
IndexSchema metaIndex = new IndexSchema();
metaIndex.setFieldSchemas(Arrays.asList(
        new FieldSchema("type", FieldType.KEYWORD).setIndex(true).setEnableSortAndAgg(true),
        new FieldSchema("group_name", FieldType.TEXT).setIndex(true).setAnalyzer(FieldSchema.Analyzer.MaxWord)
));
TimelineMetaSchema metaSchema = new TimelineMetaSchema("im_timeline_meta_table", idSchema)
        .withIndex("im_timeline_meta_index", metaIndex);
TimelineMetaStore metaStore = serviceFactory.createMetaStore(metaSchema);

// Store library: persists all conversation messages with search index for full-text search
IndexSchema storeIndex = new IndexSchema();
storeIndex.setFieldSchemas(Arrays.asList(
        new FieldSchema("timeline_id", FieldType.KEYWORD).setIndex(true),
        new FieldSchema("text", FieldType.TEXT).setIndex(true).setAnalyzer(FieldSchema.Analyzer.MaxWord),
        new FieldSchema("sender", FieldType.KEYWORD).setIndex(true),
        new FieldSchema("type", FieldType.KEYWORD).setIndex(true)
));
TimelineSchema storeSchema = new TimelineSchema("im_timeline_store_table", idSchema)
        .withIndex("im_timeline_store_index", storeIndex);
TimelineStore storeTable = serviceFactory.createTimelineStore(storeSchema);

// Sync library: per-user inbox for message fan-out, 7-day TTL
TimelineSchema syncSchema = new TimelineSchema("im_timeline_sync_table", idSchema)
        .setTimeToLive(7 * 24 * 3600);
TimelineStore syncTable = serviceFactory.createTimelineStore(syncSchema);

// Create all tables and indexes
metaStore.prepareTables();
storeTable.prepareTables();
syncTable.prepareTables();

In addition to the three tables managed by the Timeline SDK, you must manually create the user table, friend relationship table, and group relationship table. The group relationship table requires a secondary index for reverse queries.

// Create user table
TableMeta userMeta = new TableMeta("im_user_table");
userMeta.addPrimaryKeyColumn("user_id", PrimaryKeyType.STRING);
syncClient.createTable(new CreateTableRequest(userMeta, new TableOptions(-1, 1)));

// Create user relation table (for friendship)
TableMeta relationMeta = new TableMeta("im_user_relation_table");
relationMeta.addPrimaryKeyColumn("main_user", PrimaryKeyType.STRING);
relationMeta.addPrimaryKeyColumn("sub_user", PrimaryKeyType.STRING);
syncClient.createTable(new CreateTableRequest(relationMeta, new TableOptions(-1, 1)));

// Create group relation table with global secondary index
TableMeta groupMeta = new TableMeta("im_group_relation_table");
groupMeta.addPrimaryKeyColumn("group_id", PrimaryKeyType.STRING);
groupMeta.addPrimaryKeyColumn("user_id", PrimaryKeyType.STRING);
CreateTableRequest groupRequest = new CreateTableRequest(groupMeta, new TableOptions(-1, 1));

// Global secondary index: reverse PK order (user_id, group_id) for "list my groups"
IndexMeta indexMeta = new IndexMeta("im_group_relation_global_index");
indexMeta.addPrimaryKeyColumn("user_id");
indexMeta.addPrimaryKeyColumn("group_id");
groupRequest.addIndex(indexMeta);
syncClient.createTable(groupRequest);

Step 2: Create a user

Write user information to the user table. The user_id matches the timeline_id in the sync library, so the system can directly locate the sync queue by user ID during message fan-out.

// Create a user
PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user_1"))
        .build();

RowPutChange rowPutChange = new RowPutChange("im_user_table", primaryKey);
rowPutChange.addColumn("user_name", ColumnValue.fromString("Alice"));
rowPutChange.addColumn("sexuality", ColumnValue.fromString("FEMALE"));

syncClient.putRow(new PutRowRequest(rowPutChange));

Step 3: Manage friend relationships

Friend relationships are bidirectional. When adding a friend, use BatchWriteRow to write two rows simultaneously (A to B and B to A) so that both users can find each other through GetRange. Removing a friend also uses BatchWriteRow to delete both rows.

// Establish bidirectional friendship between userA and userB
String userA = "user_1";
String userB = "user_2";
String timelineId = "single_conv_1";  // Shared conversation timeline ID

// Row A -> B
PrimaryKey pkA = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("main_user", PrimaryKeyValue.fromString(userA))
        .addPrimaryKeyColumn("sub_user", PrimaryKeyValue.fromString(userB))
        .build();
RowPutChange changeA = new RowPutChange("im_user_relation_table", pkA);
changeA.addColumn("timeline_id", ColumnValue.fromString(timelineId));

// Row B -> A
PrimaryKey pkB = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("main_user", PrimaryKeyValue.fromString(userB))
        .addPrimaryKeyColumn("sub_user", PrimaryKeyValue.fromString(userA))
        .build();
RowPutChange changeB = new RowPutChange("im_user_relation_table", pkB);
changeB.addColumn("timeline_id", ColumnValue.fromString(timelineId));

// Batch write for atomicity
BatchWriteRowRequest request = new BatchWriteRowRequest();
request.addRowChange(changeA);
request.addRowChange(changeB);
syncClient.batchWriteRow(request);

To list a user's friends, use the current user's ID as main_user and scan all sub_user values through GetRange.

// List friends of a user
PrimaryKey start = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("main_user", PrimaryKeyValue.fromString("user_1"))
        .addPrimaryKeyColumn("sub_user", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey end = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("main_user", PrimaryKeyValue.fromString("user_1"))
        .addPrimaryKeyColumn("sub_user", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("im_user_relation_table");
criteria.setInclusiveStartPrimaryKey(start);
criteria.setExclusiveEndPrimaryKey(end);
criteria.setMaxVersions(1);

GetRangeResponse response = syncClient.getRange(new GetRangeRequest(criteria));
for (Row row : response.getRows()) {
    String friendId = row.getPrimaryKey().getPrimaryKeyColumn("sub_user").getValue().asString();
    System.out.println("Friend: " + friendId);
}

Step 4: Manage groups

To create a group, write the group information (group name, type, and creation time) to the Timeline meta library, and then add the group members to the group relationship table.

// Create a group conversation in the meta library
TimelineIdentifier identifier = new TimelineIdentifier.Builder()
        .addField("timeline_id", "group_1")
        .build();
TimelineMeta meta = new TimelineMeta(identifier)
        .setField("type", "GROUP")
        .setField("group_name", "Tablestore Discussion")
        .setField("create_time", System.currentTimeMillis());
metaStore.insert(meta);

// Add members to the group relation table
String[] members = {"user_1", "user_2", "user_3"};
for (String userId : members) {
    PrimaryKey pk = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn("group_id", PrimaryKeyValue.fromString("group_1"))
            .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString(userId))
            .build();
    syncClient.putRow(new PutRowRequest(new RowPutChange("im_group_relation_table", pk)));
}

The primary key of the group relationship table is group_id + user_id. GetRange lists all members in a group. The secondary index im_group_relation_global_index reverses the primary key order to user_id + group_id, which enables reverse queries to list all groups that a user has joined.

// List groups that a user has joined (via global secondary index)
PrimaryKey start = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user_1"))
        .addPrimaryKeyColumn("group_id", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey end = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user_1"))
        .addPrimaryKeyColumn("group_id", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria criteria = new RangeRowQueryCriteria("im_group_relation_global_index");
criteria.setInclusiveStartPrimaryKey(start);
criteria.setExclusiveEndPrimaryKey(end);
criteria.setMaxVersions(1);

GetRangeResponse response = syncClient.getRange(new GetRangeRequest(criteria));
for (Row row : response.getRows()) {
    String groupId = row.getPrimaryKey().getPrimaryKeyColumn("group_id").getValue().asString();
    System.out.println("Joined group: " + groupId);
}

Step 5: Send messages

To send a message, write it to the store library for persistent storage, then fan it out to the recipient's sync library. For one-on-one chats, the message is fanned out to the other user's sync queue. For group chats, the message is fanned out to the sync queues of all group members.

// Send a one-on-one chat message
TimelineMessage message = new TimelineMessage()
        .setField("text", "Hello, how are you?")
        .setField("type", "SINGLE")
        .setField("sender", "user_2")
        .setField("send_time", System.currentTimeMillis())
        .setField("conversation", "user_2");

// Step 1: Write to the store library (persistent storage)
TimelineIdentifier storeId = new TimelineIdentifier.Builder()
        .addField("timeline_id", "single_conv_1")
        .build();
storeTable.createTimelineQueue(storeId).store(message);

// Step 2: Fan out to the receiver's sync library
TimelineIdentifier syncId = new TimelineIdentifier.Builder()
        .addField("timeline_id", "user_1")  // Receiver's user ID
        .build();
syncTable.createTimelineQueue(syncId).store(message);

// Send a group chat message (fan out to all group members)
TimelineMessage groupMsg = new TimelineMessage()
        .setField("text", "Who used Tablestore today?")
        .setField("type", "GROUP")
        .setField("sender", "user_1")
        .setField("send_time", System.currentTimeMillis())
        .setField("conversation", "group_1");

// Step 1: Write to the store library
TimelineIdentifier storeId = new TimelineIdentifier.Builder()
        .addField("timeline_id", "group_1")
        .build();
storeTable.createTimelineQueue(storeId).store(groupMsg);

// Step 2: Fan out to each group member's sync library
// Get group members from the group relation table, then write to each member's sync queue
for (String memberId : groupMemberIds) {
    TimelineIdentifier syncId = new TimelineIdentifier.Builder()
            .addField("timeline_id", memberId)
            .build();
    syncTable.createTimelineQueue(syncId).store(groupMsg);
}

Step 6: Synchronize messages and count unread messages

The client maintains a checkpoint (the sequenceId of the last message read). Use ScanParameter to incrementally pull new messages from the sync library starting from the checkpoint, then group the messages by conversation to count unread messages.

// Fetch new messages from the sync library
long syncCheckpoint = 0;  // Last read position, maintained by the client

TimelineIdentifier identifier = new TimelineIdentifier.Builder()
        .addField("timeline_id", "user_1")
        .build();

ScanParameter parameter = new ScanParameter()
        .scanForward(syncCheckpoint + 1)
        .maxCount(30);

Iterator<TimelineEntry> iterator = syncTable.createTimelineQueue(identifier).scan(parameter);

// Group messages by conversation and count unread messages
Map<String, Integer> unreadCount = new HashMap<>();
while (iterator.hasNext()) {
    TimelineEntry entry = iterator.next();
    String conversation = entry.getMessage().getString("conversation");
    unreadCount.merge(conversation, 1, Integer::sum);

    // Update checkpoint to the latest sequenceId
    syncCheckpoint = Math.max(syncCheckpoint, entry.getSequenceID());
}

for (Map.Entry<String, Integer> e : unreadCount.entrySet()) {
    System.out.println("Conversation: " + e.getKey() + ", Unread: " + e.getValue());
}

To view the message history of a conversation, pull messages from the store library in reverse order.

// Fetch conversation history from the store library (reverse order)
TimelineIdentifier storeId = new TimelineIdentifier.Builder()
        .addField("timeline_id", "group_1")
        .build();

ScanParameter parameter = new ScanParameter()
        .scanBackward(Long.MAX_VALUE - 1)
        .maxCount(30);

Iterator<TimelineEntry> iterator = storeTable.createTimelineQueue(storeId).scan(parameter);
while (iterator.hasNext()) {
    TimelineEntry entry = iterator.next();
    String sender = entry.getMessage().getString("sender");
    String text = entry.getMessage().getString("text");
    System.out.println("[" + sender + "]: " + text);
}

Step 7: Search messages

The store library uses the search index im_timeline_store_index to support full-text search by conversation ID and message content. The meta library uses the search index im_timeline_meta_index to support fuzzy search by group name.

// Search messages in a specific conversation by content keyword
TermQuery termQuery = new TermQuery();
termQuery.setFieldName("timeline_id");
termQuery.setTerm(ColumnValue.fromString("group_1"));

MatchPhraseQuery matchQuery = new MatchPhraseQuery();
matchQuery.setFieldName("text");
matchQuery.setText("Tablestore");

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(Arrays.asList(termQuery, matchQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);
searchQuery.setLimit(30);

List<SearchResult.Entry<TimelineEntry>> results = storeTable.search(searchQuery).getEntries();
for (SearchResult.Entry<TimelineEntry> result : results) {
    TimelineEntry entry = result.getData();
    System.out.println("[" + entry.getMessage().getString("sender") + "]: "
            + entry.getMessage().getString("text"));
}

// Search group conversations by group name
TermQuery typeQuery = new TermQuery();
typeQuery.setFieldName("type");
typeQuery.setTerm(ColumnValue.fromString("GROUP"));

MatchPhraseQuery nameQuery = new MatchPhraseQuery();
nameQuery.setFieldName("group_name");
nameQuery.setText("Tablestore");

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(Arrays.asList(typeQuery, nameQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);
searchQuery.setLimit(100);

List<SearchResult.Entry<TimelineMeta>> results = metaStore.search(searchQuery).getEntries();
for (SearchResult.Entry<TimelineMeta> result : results) {
    TimelineMeta meta = result.getData();
    System.out.println("Group: " + meta.getString("group_name"));
}