Skip to content

Commit 879b3ee

Browse files
clunclun
committed
Improve Read me
1 parent 1a1d31a commit 879b3ee

File tree

3 files changed

+178
-10
lines changed

3 files changed

+178
-10
lines changed

‎README.MD

Lines changed: 126 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ This client library provides a simplified way to interact with Data API for Astr
2424
This library is under development and is available in Maven Central.
2525
You can build it locally and install it in your local repository.
2626

27-
## 1. Local Installation
27+
## 1. Installation
2828

2929
### 1.1 Prerequisites
3030

@@ -67,23 +67,59 @@ git clone [email protected]:datastax/astra-db-java.git
6767
mvn clean install -Dtest.skipped=true
6868
```
6969

70-
### 1.3 Installation
70+
## 2. QuickStart with Astra DB
71+
72+
### 2.1. Sign up for Astra DB
73+
74+
- Access [https://astra.datastax.com](https://astra.datastax.com) and register with `Google` or `Github` account. It is free to use. There is free forever tiers of up to 25$ of consumption every month.
75+
76+
![](https://awesome-astra.github.io/docs/img/astra/astra-signin-github-0.png)
77+
78+
### 2.2. Create a Database
79+
80+
> If you are creating a new account, you will be brought to the DB-creation form directly.
81+
82+
- Get to the databases dashboard (by clicking on Databases in the left-hand navigation bar, expanding it if necessary), and click the `[Create Database]` button on the right.
83+
84+
![](https://datastaxdevs.github.io/langchain4j/langchain4j-1.png)
85+
86+
- **ℹ️ Fields Description**
87+
88+
| Field | Description |
89+
|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
90+
| **Vector Database vs Serverless Database** | Choose `Vector Database` In june 2023, Cassandra introduced the support of vector search to enable Generative AI use cases. |
91+
| **Database name** | It does not need to be unique, is not used to initialize a connection, and is only a label (keep it between 2 and 50 characters). It is recommended to have a database for each of your applications. The free tier is limited to 5 databases. |
92+
| **Cloud Provider** | Choose whatever you like. Click a cloud provider logo, pick an Area in the list and finally pick a region. We recommend choosing a region that is closest to you to reduce latency. In free tier, there is very little difference. |
93+
| **Cloud Region** | Pick region close to you available for selected cloud provider and your plan. |
94+
95+
If all fields are filled properly, clicking the "Create Database" button will start the process.
96+
97+
![](https://datastaxdevs.github.io/langchain4j/langchain4j-2.png)
98+
99+
It should take a couple of minutes for your database to become `Active`.
100+
101+
![](https://datastaxdevs.github.io/langchain4j/langchain4j-3.png)
102+
103+
### 2.3. Get your credentials
104+
105+
To connect to your database, you need the API Endpoint and a token. The api endpoint is available on the database screen, there is a little icon to copy the URL in your clipboard. (it should look like `https://<db-id>-<db-region>.apps.astra.datastax.com`).
106+
107+
![](https://datastaxdevs.github.io/langchain4j/langchain4j-4.png)
108+
109+
To get a token click the `[Generate Token]` button on the right. It will generate a token that you can copy to your clipboard.
110+
111+
### 2.4 Create a new project and add the dependency
71112

72113
Add the following dependency to your `pom.xml` file:
73114

74115
```xml
75-
76116
<dependency>
77117
<groupId>com.datastax.astra</groupId>
78118
<artifactId>astra-db-java</artifactId>
79-
<version>1.0.0</version>
119+
<version>1.1.0</version>
80120
</dependency>
81121
```
82122

83-
## 2. QuickStart
84-
85-
After creating a new java Project and adding the dependency to your `pom.xml` file, you can start using the library.
86-
87123
Here is a sample class that demonstrates how to use the library:
88124

89125
```java
@@ -126,7 +162,88 @@ public class GettingStarted {
126162
}
127163
```
128164

129-
### 3. What's Next
165+
## 3. QuickStart with Local Instance
166+
167+
### 3.1. Start Data Api.
168+
169+
- Start the 2 containers with the following command:
170+
171+
```console
172+
docker-compose up -d
173+
```
174+
175+
- Check the status of the containers with the following command:
176+
177+
```console
178+
docker-compose ps
179+
```
180+
181+
> _Output_
182+
> ```console
183+
> NAME IMAGE COMMAND
184+
> astra-db-java-coordinator-1 stargateio/coordinator-dse-next:v2.1.0-BETA-9 "./starctl"
185+
> astra-db-java-jsonapi-1 stargateio/jsonapi:v1.0.6
186+
> ```
187+
188+
- Here are the information to connect to the local instance:
189+
190+
| Field | Description |
191+
|--------------------------------------------|-----------------------------------------------------------------------------------------|
192+
| **Data API Spec** | http://localhost:8181/swagger-ui/#/ |
193+
| **Data API Endpoint** | http://localhost:8181 |
194+
| **Token Header Key** | `Token` |
195+
| **Token Header Value** | `Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh` (aka `Cassandra:Base64(userName):Base64(password)`) |
196+
| **Authentication API Spec (before 1.0.6)** | http://localhost:8081/swagger-ui/#/ |
197+
198+
- The API will have 3 resources
199+
200+
| Field | Url | Description |
201+
|-----------------------|--------------------------------|---------------------------------------------------|
202+
| **Namespace** | `/v1/` | Interact with namespaces (not available in Astra) |
203+
| **Data API Endpoint** | `/v1/{namespace}` | Interact with collections of a namespace |
204+
| **Token Header Key** | `/v1/{namespace}/{collection}` |Interact with documents of a collection |
205+
206+
- Sample curl to create a namespace:
207+
208+
```console
209+
curl -X 'POST' \
210+
'http://localhost:8181/v1' \
211+
-H 'accept: application/json' \
212+
-H 'Token: Cassandra:Y2Fzc2FuZHJh:Y2Fzc2FuZHJh' \
213+
-H 'Content-Type: application/json' \
214+
-d '{
215+
"createNamespace": {
216+
"name": "cycling"
217+
}
218+
}'
219+
```
220+
221+
### 3.2. Using Java client with local instance
222+
223+
```java
224+
public class QuickStartLocal {
225+
226+
public static void main(String[] args) {
227+
228+
// Create a token
229+
String token = new TokenProviderStargateV2("cassandra", "cassandra").getToken();
230+
System.out.println("Token: " + token);
231+
232+
// Initialize the client
233+
DataAPIClient client = new DataAPIClient(token, builder().withDestination(CASSANDRA).build());
234+
System.out.println("Connected to Data API");
235+
236+
Database db = client.getDatabase("http://localhost:8181", "default_keyspace");
237+
System.out.println("Connected to Database");
238+
239+
// Create a collection. The default similarity metric is cosine.
240+
Collection<Document> collection = db.createCollection("vector_test", 5, COSINE);
241+
System.out.println("Created a Collection");
242+
}
243+
}
244+
```
245+
246+
## 4. What's Next
130247

131248
This is an the organization of the different classes of the framework.
132249

‎examples/src/main/java/QuickStartLocal.java

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import com.datastax.astra.client.Collection;
2+
import com.datastax.astra.client.DataAPIClient;
3+
import com.datastax.astra.client.Database;
4+
import com.datastax.astra.client.model.Document;
5+
import com.datastax.astra.client.model.FindIterable;
6+
import com.datastax.astra.internal.auth.TokenProviderStargateV2;
7+
8+
import static com.datastax.astra.client.DataAPIOptions.DataAPIDestination.CASSANDRA;
9+
import static com.datastax.astra.client.DataAPIOptions.builder;
10+
import static com.datastax.astra.client.model.SimilarityMetric.COSINE;
11+
12+
public class QuickStartLocal {
13+
14+
public static void main(String[] args) {
15+
16+
// Create a token
17+
String token = new TokenProviderStargateV2("cassandra", "cassandra").getToken();
18+
System.out.println("Token: " + token);
19+
20+
// Initialize the client
21+
DataAPIClient client = new DataAPIClient(token, builder().withDestination(CASSANDRA).build());
22+
System.out.println("Connected to Data API");
23+
24+
Database db = client.getDatabase("http://localhost:8181", "default_keyspace");
25+
System.out.println("Connected to Database");
26+
27+
// Create a collection. The default similarity metric is cosine.
28+
Collection<Document> collection = db.createCollection("vector_test", 5, COSINE);
29+
System.out.println("Created a Collection");
30+
31+
collection.insertMany(
32+
new Document("1")
33+
.append("text", "ChatGPT integrated sneakers that talk to you")
34+
.vector(new float[]{0.1f, 0.15f, 0.3f, 0.12f, 0.05f}),
35+
new Document("2")
36+
.append("text", "An AI quilt to help you sleep forever")
37+
.vector(new float[]{0.45f, 0.09f, 0.01f, 0.2f, 0.11f}),
38+
new Document("3")
39+
.append("text", "A deep learning display that controls your mood")
40+
.vector(new float[]{0.1f, 0.05f, 0.08f, 0.3f, 0.6f}));
41+
System.out.println("Inserted documents into the collection");
42+
43+
FindIterable<Document> resultsSet = collection.find(
44+
new float[]{0.15f, 0.1f, 0.1f, 0.35f, 0.55f},
45+
10
46+
);
47+
resultsSet.forEach(System.out::println);
48+
collection.drop();
49+
System.out.println("Deleted the collection");
50+
}
51+
}

‎examples/src/main/java/com/datastax/astra/client/DataApiClient.java renamed to ‎examples/src/main/java/com/datastax/astra/client/DataApiClientDemo.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
import static com.datastax.astra.client.model.SimilarityMetric.COSINE;
1010

11-
public class DataApiClient {
11+
public class DataApiClientDemo {
1212
public static void main(String[] args) {
1313
DataAPIClient client = new DataAPIClient("TOKEN");
1414
Database database0 = client.getDatabase("API_ENDPOINT");

0 commit comments

Comments
 (0)