This document guides you on how to use Java Client through some simple examples. For more details, please visit TiKV Java Client User Documents.

TiKV Java Client is developed and released using Java8. The minimum supported version of TiKV is 2.0.0.

Add the dependency

To start, open the pom.xml of your project, and add the tikv-client-java as dependencies if you are using Maven.

1. <dependency>
2. <groupId>org.tikv</groupId>
3. <artifactId>tikv-client-java</artifactId>
4. <version>3.2.0</version>
5. </dependency>

Try the transactional key-value API

Below is the basic usages of TxnKV. Data should be written into TxnKV using TwoPhaseCommitter, and be read using org.tikv.txn.KVClient.

1. import java.util.Arrays;
2. import java.util.List;

4. import org.tikv.common.BytePairWrapper;
5. import org.tikv.common.ByteWrapper;
6. import org.tikv.common.TiConfiguration;
7. import org.tikv.common.TiSession;
8. import org.tikv.common.util.BackOffer;
9. import org.tikv.common.util.ConcreteBackOffer;
10. import org.tikv.kvproto.Kvrpcpb.KvPair;
11. import org.tikv.shade.com.google.protobuf.ByteString;
12. import org.tikv.txn.KVClient;
13. import org.tikv.txn.TwoPhaseCommitter;

15. public class App {
16. public static void main(String[] args) throws Exception {
17. TiConfiguration conf = TiConfiguration.createDefault("127.0.0.1:2379");
18. try (TiSession session = TiSession.create(conf)) {
19. // two-phase write
20. long startTS = session.getTimestamp().getVersion();
21. try (TwoPhaseCommitter twoPhaseCommitter = new TwoPhaseCommitter(session, startTS)) {
22. BackOffer backOffer = ConcreteBackOffer.newCustomBackOff(1000);
23. byte[] primaryKey = "key1".getBytes("UTF-8");
24. byte[] key2 = "key2".getBytes("UTF-8");

26. // first phase: prewrite
27. twoPhaseCommitter.prewritePrimaryKey(backOffer, primaryKey, "val1".getBytes("UTF-8"));
28. List<BytePairWrapper> pairs = Arrays
29. .asList(new BytePairWrapper(key2, "val2".getBytes("UTF-8")));
30. twoPhaseCommitter.prewriteSecondaryKeys(primaryKey, pairs.iterator(), 1000);

32. // second phase: commit
33. long commitTS = session.getTimestamp().getVersion();
34. twoPhaseCommitter.commitPrimaryKey(backOffer, primaryKey, commitTS);
35. List<ByteWrapper> keys = Arrays.asList(new ByteWrapper(key2));
36. twoPhaseCommitter.commitSecondaryKeys(keys.iterator(), commitTS, 1000);
37. }

39. try (KVClient kvClient = session.createKVClient()) {
40. long version = session.getTimestamp().getVersion();
41. ByteString key1 = ByteString.copyFromUtf8("key1");
42. ByteString key2 = ByteString.copyFromUtf8("key2");

44. // get value of a single key
45. ByteString val = kvClient.get(key1, version);
46. System.out.println(val);

48. // get value of multiple keys
49. BackOffer backOffer = ConcreteBackOffer.newCustomBackOff(1000);
50. List<KvPair> kvPairs = kvClient.batchGet(backOffer, Arrays.asList(key1, key2), version);
51. System.out.println(kvPairs);

53. // get value of a range of keys
54. kvPairs = kvClient.scan(key1, ByteString.copyFromUtf8("key3"), version);
55. System.out.println(kvPairs);
56. }
57. }
58. }
59. }

Try the Raw key-value API

Below is the basic usages of RawKV.

1. import java.util.ArrayList;
2. import java.util.List;
3. import java.util.Optional;
4. import org.tikv.common.TiConfiguration;
5. import org.tikv.common.TiSession;
6. import org.tikv.kvproto.Kvrpcpb;
7. import org.tikv.raw.RawKVClient;
8. import org.tikv.shade.com.google.protobuf.ByteString;

10. public class Main {
11. public static void main(String[] args) throws Exception {
12. // You MUST create a raw configuration if you are using RawKVClient.
13. TiConfiguration conf = TiConfiguration.createRawDefault("127.0.0.1:2379");
14. TiSession session = TiSession.create(conf);
15. RawKVClient client = session.createRawClient();

17. // put
18. client.put(ByteString.copyFromUtf8("k1"), ByteString.copyFromUtf8("Hello"));
19. client.put(ByteString.copyFromUtf8("k2"), ByteString.copyFromUtf8(","));
20. client.put(ByteString.copyFromUtf8("k3"), ByteString.copyFromUtf8("World"));
21. client.put(ByteString.copyFromUtf8("k4"), ByteString.copyFromUtf8("!"));
22. client.put(ByteString.copyFromUtf8("k5"), ByteString.copyFromUtf8("Raw KV"));

24. // get
25. Optional<ByteString> result = client.get(ByteString.copyFromUtf8("k1"));
26. System.out.println(result.get().toStringUtf8());

28. // batch get
29. List<Kvrpcpb.KvPair> list = client.batchGet(new ArrayList<ByteString>() {{
30. add(ByteString.copyFromUtf8("k1"));
31. add(ByteString.copyFromUtf8("k3"));
32. }});
33. System.out.println(list);

35. // scan
36. list = client.scan(ByteString.copyFromUtf8("k1"), ByteString.copyFromUtf8("k6"), 10);
37. System.out.println(list);

39. // close
40. client.close();
41. session.close();
42. }
43. }