Skip to content

Commit 969774d

Browse files
author
Thanh Nguyen
committed
update docs
1 parent 038911f commit 969774d

File tree

3 files changed

+338
-275
lines changed

3 files changed

+338
-275
lines changed

‎README.md

+114-111
Original file line numberDiff line numberDiff line change
@@ -7,82 +7,34 @@
77
[![Release](https://img.shields.io/github/release/btnguyen2k/gocosmos.svg?style=flat-square)](RELEASE-NOTES.md)
88
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#database-drivers)
99

10-
Go driver for [Azure Cosmos DB SQL API](https://azure.microsoft.com/en-us/services/cosmos-db/) which can be used with the standard [database/sql](https://golang.org/pkg/database/sql/) package. A REST client for [Azure Cosmos DB SQL API](https://azure.microsoft.com/en-us/services/cosmos-db/) is also included.
10+
Go driver for [Azure Cosmos DB SQL API](https://azure.microsoft.com/services/cosmos-db/) which can be used with the standard [database/sql](https://golang.org/pkg/database/sql/) package. A REST client is also included.
1111

12-
## Example usage: REST client
12+
## database/sql driver
1313

14-
```go
15-
import (
16-
"os"
17-
"database/sql"
18-
"github.com/btnguyen2k/gocosmos"
19-
)
20-
21-
func main() {
22-
cosmosDbConnStr := "AccountEndpoint=https://localhost:8081/;AccountKey=<cosmosdb-account-key>"
23-
client, err := gocosmos.NewRestClient(nil, cosmosDbConnStr)
24-
if err != nil {
25-
panic(err)
26-
}
27-
28-
dbSpec := gocosmos.DatabaseSpec{Id:"mydb", Ru: 400}
29-
result := client.CreateDatabase(dbSpec)
30-
if result.Error() != nil {
31-
panic(result.Error)
32-
}
33-
34-
// database "mydb" has been created successfuly
35-
}
36-
```
37-
38-
**Connection string syntax for Cosmos DB**
39-
40-
> `AccountEndpoint=<cosmosdb-endpoint>;AccountKey=<cosmosdb-account-key>;TimeoutMs=<timeout-in-ms>;Version=<cosmosdb-api-version>;AutoId=<true/false>;InsecureSkipVerify=<true/false>`
41-
42-
- `AccountEndpoint`: (required) endpoint to access Cosmos DB. For example, the endpoint for Azure Cosmos DB Emulator running on local is `https://localhost:8081/`.
43-
- `AccountKey`: (required) account key to authenticate.
44-
- `TimeoutMs`: (optional) operation timeout in milliseconds. Default value is `10 seconds` if not specified.
45-
- `Version`: (optional) version of Cosmos DB to use. Default value is `2018-12-31` if not specified. See: https://docs.microsoft.com/en-us/rest/api/cosmos-db/#supported-rest-api-versions.
46-
- `AutoId`: (optional, available since [v0.1.2](RELEASE-NOTES.md)) see [auto id](#auto-id) session.
47-
- `InsecureSkipVerify`: (optional, available since [v0.1.4](RELEASE-NOTES.md)) if `true`, disable CA verification for https endpoint (useful to run against test/dev env with local/docker Cosmos DB emulator).
48-
49-
### Known issues
50-
51-
**`GROUP BY` combined with `ORDER BY` is not supported**
52-
53-
Azure Cosmos DB does not support `GROUP BY` combined with `ORDER BY` yet. You will receive the following error message:
54-
55-
> 'ORDER BY' is not supported in presence of GROUP BY.
56-
57-
**Cross-partition queries**
58-
59-
When documents are spanned across partitions, they must be fetched from multiple `PkRangeId` and then merged to build
60-
the final result. Due to this behaviour, some cross-partition queries might not work as expected.
14+
Summary of supported SQL statements:
6115

62-
- *Paging cross-partition `OFFSET...LIMIT` queries using `max-count-item`*:<br>
63-
Since documents must be fetched from multiple `PkRangeId`, the result is nondeterministic.
64-
Moreover, calls to `RestClient.QueryDocumentsCrossPartition(...)` and `RestClient.QueryDocuments(...)` without
65-
pagination (i.e. set `MaxCountItem=0`) may yield different results.
16+
|Statement|Syntax|
17+
|---------|-----------|
18+
|Create a new database |`CREATE DATABASE [IF NOT EXISTS] <db-name>`|
19+
|Change database's throughput |`ALTER DATABASE <db-name> WITH RU/MAXRU=<ru>`|
20+
|Delete an existing database |`DROP DATABASE [IF EXISTS] <db-name>`|
21+
|List all existing databases |`LIST DATABASES`|
22+
|Create a new collection |`CREATE COLLECTION [IF NOT EXISTS] [<db-name>.]<collection-name> <WITH [LARGE]PK=partitionKey>`|
23+
|Change collection's throughput |`ALTER COLLECTION [<db-name>.]<collection-name> WITH RU/MAXRU=<ru>`|
24+
|Delete an existing collection |`DROP COLLECTION [IF EXISTS] [<db-name>.]<collection-name>`|
25+
|List all existing collections in a database|`LIST COLLECTIONS [FROM <db-name>]`|
26+
|Insert a new document into collection |`INSERT INTO [<db-name>.]<collection-name> ...`|
27+
|Insert or replace a document |`UPSERT INTO [<db-name>.]<collection-name> ...`|
28+
|Delete an existing document |`DELETE FROM [<db-name>.]<collection-name> WHERE id=<id-value>`|
29+
|Update an existing document |`UPDATE [<db-name>.]<collection-name> SET ... WHERE id=<id-value>`|
30+
|Query documents in a collection |`SELECT [CROSS PARTITION] ... FROM <collection-name> ... [WITH database=<db-name>]`|
6631

67-
- *Paging cross-partition `ORDER BY` queries with `max-count-item`*:<br>
68-
Due to the fact that documents must be fetched from multiple `PkRangeId`, rows returned from calls to
69-
`RestClient.QueryDocuments(...)` might not be in the expected order.<br>
70-
*Workaround*: if you can afford the memory, use `RestClient.QueryDocumentsCrossPartition(...)` or
71-
`RestClient.QueryDocuments(...)` without pagination (i.e. set `MaxCountItem=0`).
32+
See [supported SQL statements](SQL.md) for details.
7233

73-
- *Paging `SELECT DISTINCT` queries with `max-count-item`*:<br>
74-
Due to the fact that documents must be fetched from multiple `PkRangeId`, rows returned from calls to
75-
`RestClient.QueryDocuments(...)` might be duplicated.<br>
76-
*Workaround*: if you can afford the memory, use `RestClient.QueryDocumentsCrossPartition(...)` or
77-
`RestClient.QueryDocuments(...)` without pagination (i.e. set `MaxCountItem=0`).
78-
79-
- *`GROUP BY` combined with `max-count-item`*:<br>
80-
Due to the fact that documents must be fetched from multiple `PkRangeId`, the result returned from calls to
81-
`RestClient.QueryDocuments(...)` might not be as espected.<br>
82-
*Workaround*: if you can afford the memory, use `RestClient.QueryDocumentsCrossPartition(...)` or
83-
`RestClient.QueryDocuments(...)` without pagination (i.e. set `MaxCountItem=0`).
34+
> Azure Cosmos DB SQL API currently supports only [SELECT statement](https://learn.microsoft.com/azure/cosmos-db/nosql/query/select).
35+
> `gocosmos` implements other statements by translating the SQL statement to [REST API calls](https://learn.microsoft.com/rest/api/cosmos-db/).
8436
85-
## Example usage: database/sql driver
37+
### Example usage:
8638

8739
```go
8840
import (
@@ -110,21 +62,31 @@ func main() {
11062

11163
**Data Source Name (DSN) syntax for Cosmos DB**
11264

113-
> `AccountEndpoint=<cosmosdb-endpoint>;AccountKey=<cosmosdb-account-key>;TimeoutMs=<timeout-in-ms>;Version=<cosmosdb-api-version>;DefaultDb=<db-name>;AutoId=<true/false>;InsecureSkipVerify=<true/false>`
65+
_Note: line-break is for readability only!_
66+
67+
```connection
68+
AccountEndpoint=<cosmosdb-endpoint>
69+
;AccountKey=<cosmosdb-account-key>
70+
[;TimeoutMs=<timeout-in-ms>]
71+
[;Version=<cosmosdb-api-version>]
72+
[;DefaultDb|Db=<db-name>]
73+
[;AutoId=<true/false>]
74+
[;InsecureSkipVerify=<true/false>]
75+
```
11476

11577
- `AccountEndpoint`: (required) endpoint to access Cosmos DB. For example, the endpoint for Azure Cosmos DB Emulator running on local is `https://localhost:8081/`.
11678
- `AccountKey`: (required) account key to authenticate.
11779
- `TimeoutMs`: (optional) operation timeout in milliseconds. Default value is `10 seconds` if not specified.
118-
- `Version`: (optional) version of Cosmos DB to use. Default value is `2018-12-31` if not specified. See: https://docs.microsoft.com/en-us/rest/api/cosmos-db/#supported-rest-api-versions.
80+
- `Version`: (optional) version of Cosmos DB to use. Default value is `2018-12-31` if not specified. See: https://learn.microsoft.com/rest/api/cosmos-db/#supported-rest-api-versions.
11981
- `DefaultDb`: (optional, available since [v0.1.1](RELEASE-NOTES.md)) specify the default database used in Cosmos DB operations. Alias `Db` can also be used instead of `DefaultDb`.
12082
- `AutoId`: (optional, available since [v0.1.2](RELEASE-NOTES.md)) see [auto id](#auto-id) session.
12183
- `InsecureSkipVerify`: (optional, available since [v0.1.4](RELEASE-NOTES.md)) if `true`, disable CA verification for https endpoint (useful to run against test/dev env with local/docker Cosmos DB emulator).
12284

12385
### Auto-id
12486

125-
Azure Cosmos DB requires each document has a [unique ID](https://docs.microsoft.com/en-us/rest/api/cosmos-db/documents) that identifies the document.
87+
Azure Cosmos DB requires each document has a [unique ID](https://learn.microsoft.com/rest/api/cosmos-db/documents) that identifies the document.
12688
When creating new document, if value for the unique ID field is not supplied `gocosmos` is able to generate one automatically. This feature is enabled
127-
by specifying setting `AutoId=true` in the connection string (for REST client) or Data Source Name (for `database/sql` driver). If not specified, default
89+
by specifying setting `AutoId=true` in the Data Source Name (for `database/sql` driver) or the connection string (for REST client). If not specified, default
12890
value is `AutoId=true`.
12991

13092
_This settings is available since [v0.1.2](RELEASE-NOTES.md)._
@@ -145,53 +107,94 @@ rows from Cosmos DB. Thus, some limitations:
145107

146108
- `OFFSET...LIMIT` without `ORDER BY`:
147109

148-
## Features
110+
## REST client
149111

150112
The REST client supports:
151113
- Database: `Create`, `Get`, `Delete`, `List` and change throughput.
152114
- Collection: `Create`, `Replace`, `Get`, `Delete`, `List` and change throughput.
153115
- Document: `Create`, `Replace`, `Get`, `Delete`, `Query` and `List`.
154116

155-
The `database/sql` driver supports:
156-
- Database:
157-
- `CREATE DATABASE`
158-
- `ALTER DATABASE`
159-
- `DROP DATABASE`
160-
- `LIST DATABASES`
161-
- Table/Collection:
162-
- `CREATE TABLE/COLLECTION`
163-
- `ALTER TABLE/COLLECTION`
164-
- `DROP TABLE/COLLECTION`
165-
- `LIST TABLES/COLLECTIONS`
166-
- Item/Document:
167-
- `INSERT`
168-
- `UPSERT`
169-
- `SELECT`
170-
- `UPDATE`
171-
- `DELETE`
117+
### Example usage:
172118

173-
Summary of supported SQL statements:
119+
```go
120+
import (
121+
"os"
122+
"database/sql"
123+
"github.com/btnguyen2k/gocosmos"
124+
)
174125

175-
|Statement|Syntax|
176-
|---------|-----------|
177-
|Create a new database |`CREATE DATABASE [IF NOT EXISTS] <db-name>`|
178-
|Change database's throughput |`ALTER DATABASE <db-name> WITH RU/MAXRU=<ru>`|
179-
|Delete an existing database |`DROP DATABASE [IF EXISTS] <db-name>`|
180-
|List all existing databases |`LIST DATABASES`|
181-
|Create a new collection |`CREATE COLLECTION [IF NOT EXISTS] [<db-name>.]<collection-name> <WITH [LARGE]PK=partitionKey>`|
182-
|Change collection's throughput |`ALTER COLLECTION [<db-name>.]<collection-name> WITH RU/MAXRU=<ru>`|
183-
|Delete an existing collection |`DROP COLLECTION [IF EXISTS] [<db-name>.]<collection-name>`|
184-
|List all existing collections in a database|`LIST COLLECTIONS [FROM <db-name>]`|
185-
|Insert a new document into collection |`INSERT INTO [<db-name>.]<collection-name> ...`|
186-
|Insert or replace a document |`UPSERT INTO [<db-name>.]<collection-name> ...`|
187-
|Delete an existing document |`DELETE FROM [<db-name>.]<collection-name> WHERE id=<id-value>`|
188-
|Update an existing document |`UPDATE [<db-name>.]<collection-name> SET ... WHERE id=<id-value>`|
189-
|Query documents in a collection |`SELECT [CROSS PARTITION] ... FROM <collection-name> ... [WITH database=<db-name>]`|
126+
func main() {
127+
cosmosDbConnStr := "AccountEndpoint=https://localhost:8081/;AccountKey=<cosmosdb-account-key>"
128+
client, err := gocosmos.NewRestClient(nil, cosmosDbConnStr)
129+
if err != nil {
130+
panic(err)
131+
}
190132

191-
See [supported SQL statements](SQL.md) for details.
133+
dbSpec := gocosmos.DatabaseSpec{Id:"mydb", Ru: 400}
134+
result := client.CreateDatabase(dbSpec)
135+
if result.Error() != nil {
136+
panic(result.Error)
137+
}
138+
139+
// database "mydb" has been created successfuly
140+
}
141+
```
142+
143+
**Connection string syntax for Cosmos DB**
144+
145+
_Note: line-break is for readability only!_
146+
147+
```
148+
AccountEndpoint=<cosmosdb-endpoint>
149+
;AccountKey=<cosmosdb-account-key>
150+
[;TimeoutMs=<timeout-in-ms>]
151+
[;Version=<cosmosdb-api-version>]
152+
[;AutoId=<true/false>]
153+
[;InsecureSkipVerify=<true/false>`]
154+
```
155+
156+
- `AccountEndpoint`: (required) endpoint to access Cosmos DB. For example, the endpoint for Azure Cosmos DB Emulator running on local is `https://localhost:8081/`.
157+
- `AccountKey`: (required) account key to authenticate.
158+
- `TimeoutMs`: (optional) operation timeout in milliseconds. Default value is `10 seconds` if not specified.
159+
- `Version`: (optional) version of Cosmos DB to use. Default value is `2018-12-31` if not specified. See: https://learn.microsoft.com/rest/api/cosmos-db/#supported-rest-api-versions.
160+
- `AutoId`: (optional, available since [v0.1.2](RELEASE-NOTES.md)) see [auto id](#auto-id) session.
161+
- `InsecureSkipVerify`: (optional, available since [v0.1.4](RELEASE-NOTES.md)) if `true`, disable CA verification for https endpoint (useful to run against test/dev env with local/docker Cosmos DB emulator).
162+
163+
### Known issues
164+
165+
**`GROUP BY` combined with `ORDER BY` is not supported**
166+
167+
Azure Cosmos DB does not support `GROUP BY` combined with `ORDER BY` yet. You will receive the following error message:
168+
169+
> 'ORDER BY' is not supported in presence of GROUP BY.
170+
171+
**Cross-partition queries**
172+
173+
When documents are spanned across partitions, they must be fetched from multiple `PkRangeId` and then merged to build
174+
the final result. Due to this behaviour, some cross-partition queries might not work as expected.
175+
176+
- *Paging cross-partition `OFFSET...LIMIT` queries using `max-count-item`*:<br>
177+
Since documents must be fetched from multiple `PkRangeId`, the result is nondeterministic.
178+
Moreover, calls to `RestClient.QueryDocumentsCrossPartition(...)` and `RestClient.QueryDocuments(...)` without
179+
pagination (i.e. set `MaxCountItem=0`) may yield different results.
192180

193-
> Azure Cosmos DB SQL API currently supports only [SELECT statement](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-select).
194-
> `gocosmos` implements other statements by translating the SQL statement to REST API call to [Azure Cosmos DB REST API](https://docs.microsoft.com/en-us/rest/api/cosmos-db/).
181+
- *Paging cross-partition `ORDER BY` queries with `max-count-item`*:<br>
182+
Due to the fact that documents must be fetched from multiple `PkRangeId`, rows returned from calls to
183+
`RestClient.QueryDocuments(...)` might not be in the expected order.<br>
184+
*Workaround*: if you can afford the memory, use `RestClient.QueryDocumentsCrossPartition(...)` or
185+
`RestClient.QueryDocuments(...)` without pagination (i.e. set `MaxCountItem=0`).
186+
187+
- *Paging `SELECT DISTINCT` queries with `max-count-item`*:<br>
188+
Due to the fact that documents must be fetched from multiple `PkRangeId`, rows returned from calls to
189+
`RestClient.QueryDocuments(...)` might be duplicated.<br>
190+
*Workaround*: if you can afford the memory, use `RestClient.QueryDocumentsCrossPartition(...)` or
191+
`RestClient.QueryDocuments(...)` without pagination (i.e. set `MaxCountItem=0`).
192+
193+
- *`GROUP BY` combined with `max-count-item`*:<br>
194+
Due to the fact that documents must be fetched from multiple `PkRangeId`, the result returned from calls to
195+
`RestClient.QueryDocuments(...)` might not be as espected.<br>
196+
*Workaround*: if you can afford the memory, use `RestClient.QueryDocumentsCrossPartition(...)` or
197+
`RestClient.QueryDocuments(...)` without pagination (i.e. set `MaxCountItem=0`).
195198

196199
## License
197200

‎RELEASE-NOTES.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# gocosmos release notes
1+
# gocosmos - Release notes
22

3-
## 2023-06-xx - v0.2.1
3+
## 2023-06-09 - v0.2.1
44

55
- Bug fixes, Refactoring & Enhancements.
66

0 commit comments

Comments
 (0)