Skip to content

Commit c714635

Browse files
yim-leeyim-lee
authored
Update README (#12)
Add async/await examples
1 parent 4150253 commit c714635

File tree

1 file changed

+156
-56
lines changed

1 file changed

+156
-56
lines changed

‎README.md‎

Lines changed: 156 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,132 +1,232 @@
11
# Swift Cassandra Client
22

3-
CassandraClient is a Cassandra client in Swift. The client is based on [Datastax Cassandra C++ Driver](https://github.com/datastax/cpp-driver) wrapping it with Swift friendly APIs and data structures.
3+
CassandraClient is a Cassandra client in Swift. The client is based on [DataStax Cassandra C++ Driver](https://github.com/datastax/cpp-driver),
4+
wrapping it with Swift friendly APIs and data structures.
45

5-
CassandraClient API currently exposes [SwiftNIO](https://github.com/apple/swift-nio) based futures to simplify integration with SwiftNIO based servers. Swift concurrency based API is also available in Swift 5.5 and newer.
6+
CassandraClient API currently exposes [SwiftNIO](https://github.com/apple/swift-nio) based futures to
7+
simplify integration with SwiftNIO based servers. Swift concurrency based API is also available in Swift 5.5 and newer.
68

79
## Usage
810

11+
### Swift concurrency based API
12+
913
#### Creating a client instance
1014

1115
```swift
12-
let configuration = CassandraClient.Configuration(...)
13-
let cassandraClient = CassandraClient(configuration: configuration)
16+
var configuration = CassandraClient.Configuration(...)
17+
let cassandraClient = CassandraClient(configuration: configuration)
1418
```
1519

16-
The client has a default session established (lazily) so that it can be used directly to perform queries on the configured keyspace:
20+
The client has a default session established (lazily) so that it can be used directly to perform
21+
queries on the configured keyspace:
1722

1823
```swift
19-
cassandraClient.query(...)
24+
let result = try await cassandraClient.query(...)
2025
```
2126

22-
The client must be explicitly shut down when no longer needed.
27+
The client must be explicitly shut down when no longer needed:
2328

2429
```swift
25-
cassandraClient.shutdown()
30+
try cassandraClient.shutdown()
2631
```
2732

2833
#### Creating a session for a different keyspace
2934

3035
```swift
31-
let session = cassandraClient.makeSession(keyspace: "the_keyspace")
32-
session.query(...)
36+
let session = cassandraClient.makeSession(keyspace: <KEYSPACE>)
37+
let result = try await session.query(...)
3338
```
3439

35-
The session must be explicitly shut down when no longer needed.
40+
The session must be explicitly shut down when no longer needed:
3641

3742
```swift
38-
session.shutdown()
43+
try session.shutdown()
3944
```
4045

41-
You can also create a session and pass in a closure, which will automatically release the resource when the closure exists:
46+
You can also create a session and pass in a closure, which will automatically release the resource when the closure exits:
4247

4348
```swift
44-
cassandraClient.withSession(keyspace: "<keyspace>") { session in
45-
session.query(...)
46-
}
49+
try await cassandraClient.withSession(keyspace: <KEYSPACE>) { session in
50+
...
51+
}
4752
```
4853

49-
#### Running result-less commands, e.g. insert, update, delete or DDL
54+
#### Running result-less commands (e.g. insert, update, delete or DDL)
5055

5156
```swift
52-
cassandraClient.run("create table ...")
57+
try await cassandraClient.run("create table ...")
5358
```
5459

55-
Or at a session level
60+
Or at session level:
5661

5762
```swift
58-
session.run("create table ...")
63+
try await session.run("create table ...")
5964
```
6065

61-
#### Running queries returning small data-sets that fit in-memory
66+
#### Running queries returning small datasets that fit in memory
6267

63-
Returning a model object, having `Model: Codable`
68+
Returning a model object, having `Model: Codable`:
6469

6570
```swift
66-
cassandraClient.query("select * from table ...").map { (result: [Model]) in
67-
...
68-
}
69-
70-
let result: [Model] = try await cassandraClient.query("select * from table ...")
71+
let result: [Model] = try await cassandraClient.query("select * from table ...")
7172
```
7273

7374
```swift
74-
session.query("select * from table ...").map { (result: [Model]) in
75-
...
76-
}
75+
let result: [Model] = try await session.query("select * from table ...")
76+
```
7777

78-
let result: [Model] = try await session.query("select * from table ...")
78+
Or using free-form transformations on the row:
79+
80+
```swift
81+
let values = try await cassandraClient.query("select * from table ...") { row in
82+
row.column(<COLUMN_NAME>).int32
83+
}
7984
```
8085

81-
Or using free-form transformations on the row
86+
```swift
87+
let values = try await session.query("select * from table ...") { row in
88+
row.column(<COLUMN_NAME>).int32
89+
}
90+
```
91+
92+
#### Running queries returning large datasets that do not fit in memory
8293

8394
```swift
84-
cassandraClient.query("select * from table ...") { row in
85-
row.column("column_name").int32
86-
}.map { value in
87-
...
88-
}
95+
// `rows` is a sequence that one needs to iterate on
96+
let rows: Rows = try await cassandraClient.query("select * from table ...")
8997
```
9098

9199
```swift
92-
session.query("select * from table ...") { row in
93-
row.column("column_name").int32
94-
}.map { value in
95-
...
96-
}
100+
// `rows` is a sequence that one needs to iterate on
101+
let rows: Rows = try await session.query("select * from table ...")
102+
```
103+
104+
### SwiftNIO future based API
105+
106+
#### Creating a client instance
107+
108+
```swift
109+
var configuration = CassandraClient.Configuration(...)
110+
let cassandraClient = CassandraClient(configuration: configuration)
111+
```
112+
113+
The client has a default session established (lazily) so that it can be used directly to perform
114+
queries on the configured keyspace:
115+
116+
```swift
117+
let resultFuture = cassandraClient.query(...)
118+
```
119+
120+
The client must be explicitly shut down when no longer needed:
121+
122+
```swift
123+
try cassandraClient.shutdown()
124+
```
125+
126+
#### Creating a session for a different keyspace
127+
128+
```swift
129+
let session = cassandraClient.makeSession(keyspace: <KEYSPACE>)
130+
let resultFuture = session.query(...)
131+
```
132+
133+
The session must be explicitly shut down when no longer needed:
134+
135+
```swift
136+
try session.shutdown()
137+
```
138+
139+
You can also create a session and pass in a closure, which will automatically release the resource when the closure exits:
140+
141+
```swift
142+
try cassandraClient.withSession(keyspace: <KEYSPACE>) { session in
143+
...
144+
}
145+
```
146+
147+
#### Running result-less commands (e.g. insert, update, delete or DDL)
148+
149+
```swift
150+
let voidFuture = cassandraClient.run("create table ...")
151+
```
152+
153+
Or at session level:
154+
155+
```swift
156+
let voidFuture = session.run("create table ...")
97157
```
98158

99-
#### Running queries returning large data-sets that do not fit in-memory
159+
#### Running queries returning small datasets that fit in memory
160+
161+
Returning a model object, having `Model: Codable`:
100162

101163
```swift
102-
cassandraClient.query("select * from table ...").map { (rows: Rows) in
103-
// rows is a sequence that one needs to iterate on
104-
rows.map { row in
105-
...
106-
}
164+
cassandraClient.query("select * from table ...").map { result: [Model] in
165+
...
166+
}
167+
```
168+
169+
```swift
170+
session.query("select * from table ...").map { result: [Model] in
171+
...
172+
}
173+
```
174+
175+
Or using free-form transformations on the row:
176+
177+
```swift
178+
cassandraClient.query("select * from table ...") { row in
179+
row.column(<COLUMN_NAME>).int32
180+
}.map { value in
181+
...
182+
}
183+
```
184+
185+
```swift
186+
session.query("select * from table ...") { row in
187+
row.column(<COLUMN_NAME>).int32
188+
}.map { value in
189+
...
190+
}
191+
```
192+
193+
#### Running queries returning large datasets that do not fit in memory
194+
195+
```swift
196+
cassandraClient.query("select * from table ...").map { rows: Rows in
197+
// `rows` is a sequence that one needs to iterate on
198+
rows.map { row in
199+
...
107200
}
201+
}
108202
```
109203

110204
```swift
111-
session.query("select * from table ...").map { (rows: Rows) in
112-
// rows is a sequence that one needs to iterate on
113-
rows.map { row in
114-
...
115-
}
205+
session.query("select * from table ...").map { rows: Rows in
206+
// `rows` is a sequence that one needs to iterate on
207+
rows.map { row in
208+
...
116209
}
210+
}
117211
```
118212

119213
## DataStax Driver and libuv
120214

121-
The library depends on [the DataStax driver](https://github.com/datastax/cpp-driver) and [libuv](https://github.com/libuv/libuv), which are included as git submodules. Both of them have source files that are excluded in `Package.swift`.
215+
The library depends on [the DataStax driver](https://github.com/datastax/cpp-driver) and
216+
[libuv](https://github.com/libuv/libuv), which are included as git submodules. Both of them
217+
have source files that are excluded in `Package.swift`.
122218

123219
### DataStax driver
124220

125-
The git submodule is under `Sources/CDataStaxDriver/datastax-cpp-driver`. To update, do `git fetch` then checkout the desired [tag/release](https://github.com/datastax/cpp-driver/releases). The driver's config files are located in `Sources/CDataStaxDriver/extras`.
221+
The git submodule is under `Sources/CDataStaxDriver/datastax-cpp-driver`. To update,
222+
do `git fetch` then checkout the desired [tag/release](https://github.com/datastax/cpp-driver/releases). The
223+
driver's config files are located in `Sources/CDataStaxDriver/extras`.
126224

127225
### libuv
128226

129-
The git submodule is under `Sources/Clibuv/libuv`. To update, do `git fetch` then checkout the desired [tag/release](https://github.com/libuv/libuv/releases). Note that `include` and `uv.h` in `Sources/Clibuv` are symlinked to the corresponding directory/file in `Sources/Clibuv/libuv`.
227+
The git submodule is under `Sources/Clibuv/libuv`. To update, do `git fetch` then checkout
228+
the desired [tag/release](https://github.com/libuv/libuv/releases). Note that `include`
229+
and `uv.h` in `Sources/Clibuv` are symlinked to the corresponding directory/file in `Sources/Clibuv/libuv`.
130230

131231
## Development Setup
132232

0 commit comments

Comments
 (0)