Skip to content

Commit

Permalink
chore(docs): update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@btnguyen2k
btnguyen2k committed Feb 13, 2024
1 parent c7cd7de commit 5b11c91
Showing 1 changed file with 78 additions and 32 deletions.
110 changes: 78 additions & 32 deletions SQL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -299,26 +299,27 @@ Syntax:
INSERT INTO [<db-name>.]<collection-name>
(<field1>, <field2>,...<fieldN>)
VALUES (<value1>, <value2>,...<valueN>)
[WITH singlePK|SINGLE_PK[=true]]
[WITH PK=<partition-key>]
```

> `<db-name>` can be omitted if `DefaultDb` is supplied in the Data Source Name (DSN).
Since [v0.3.0](RELEASE-NOTES.md), `gocosmos` supports [Hierarchical Partition Keys](https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys) (or sub-partitions). If the collection is known not to have sub-partitions, supplying `WITH singlePK` (or `WITH SINGLE_PK`) can save one roundtrip to Cosmos DB server.
> `<db-name>` can be omitted if `DefaultDb` is supplied in the [Data Source Name (DSN)](README.md#example-usage).
Example:
```go
sql := `INSERT INTO mydb.mytable (a, b, c, d, e) VALUES (1, "\"a string\"", :1, @2, $3)`
dbresult, err := db.Exec(sql, true, []interface{}{1, true, nil, "string"}, map[string]interface{}{"key":"value"}, "mypk")
sql := `INSERT INTO mydb.mytable (id, a, b, c, d) VALUES (1, "\"a string\"", :1, @2, $3) WITH pk=/id`
params := []interface{}{
true, // value for :1
[]interface{}{1, true, nil, "string"}, // value for @2
map[string]interface{}{"key":"value"}, // value for $3
}
dbresult, err := db.Exec(sql, params...)
if err != nil {
panic(err)
}
fmt.Println(dbresult.RowsAffected())
fmt.Println(dbresult.RowsAffected()) // output 1
```

> Use `sql.DB.Exec` to execute the statement, `Query` will return error.
> Values of partition keys _must_ be supplied at the end of the argument list when invoking `db.Exec()`.
> Use `sql.DB.Exec` to execute the statement, `Query` will return error!
<a id="value"></a>A value is either:
- a placeholder - which is a number prefixed by `$` or `@` or `:`, for example `$1`, `@2` or `:3`. Placeholders are 1-based index, that means starting from 1.
Expand All @@ -333,19 +334,53 @@ fmt.Println(dbresult.RowsAffected())
- a map value in JSON (include the double quotes), for example `"{\"key\":\"value\"}"`
- a list value in JSON (include the double quotes), for example `"[1,true,null,\"string\"]"`

Example:
```sql
INSERT INTO mydb.mytable (
id,
anull,
anum,
abool,
jstring,
jnum,
jbool,
jnull,
jmap,
jlist) VALUES (
:1,
NULL,
1.23,
true,
"\"a string\"",
"123",
"true",
"null",
"{\"key1\":\"value\",\"key2\": 2.34, \"key3\": false, \"key4\": null}",
"[1,true,null,\"string\"]"
) WITH PK=/id
```

**Since <<VERSION>>**:

- `WITH SINGLE_PK` is deprecated and will be _removed_ in future version! Instead, use `WITH PK=/pkey` (or `WITH PK=/pkey1,/pkey2` if [Hierarchical Partition Keys](https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys) - also known as sub-partitions - is used on the collection).
- Supplying values for partition key at the end of parameter list is no longer required, but still supported for backward compatibility. This behaviour will be _removed_ in future version!

> `gocosmos` automatically discovers PK of the collection by fetching metadata from server.
> Using `WITH PK` will save one round-trip to Cosmos DB server to fetch the collection's partition key info.
[Back to top](#top)

#### UPSERT

Description: insert a new document or replace an existing one.
Description: insert a new document _or replace_ an existing one.

Syntax & Usage: similar to [INSERT](#insert).

```sql
UPSERT INTO [<db-name>.]<collection-name>
(<field1>, <field2>,...<fieldN>)
VALUES (<value1>, <value2>,...<valueN>)
[WITH singlePK|SINGLE_PK[=true]]
[WITH PK=<partition-key>]
```

[Back to top](#top)
Expand All @@ -357,32 +392,38 @@ Description: delete an existing document.
Syntax:

```sql
DELETE FROM [<db-name>.]<collection-name>
DELETE FROM <db-name>.<collection-name>
WHERE id=<id-value>
[WITH singlePK|SINGLE_PK[=true]]
[AND pkfield1=<pk1-value> [AND pkfield2=<pk2-value> ...]]
```

> `<db-name>` can be omitted if `DefaultDb` is supplied in the Data Source Name (DSN).
`gocosmos` supports [Hierarchical Partition Keys](https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys) (or sub-partitions). If the collection is known not to have sub-partitions, supplying `WITH singlePK` (or `WITH SINGLE_PK`) can save one roundtrip to Cosmos DB server.

Example:
```go
sql := `DELETE FROM mydb.mytable WHERE id=@1`
sql := `DELETE FROM mydb.mytable WHERE id=@1 AND pk=@2`
dbresult, err := db.Exec(sql, "myid", "mypk")
if err != nil {
panic(err)
}
fmt.Println(dbresult.RowsAffected())
fmt.Println(dbresult.RowsAffected()) // output 1
```

> Use `sql.DB.Exec` to execute the statement, `Query` will return error.
> Values of partition keys _must_ be supplied at the end of the argument list when invoking `db.Exec()`.
- `DELETE` removes only one document specified by id.
- The clause `WHERE id=<id-value>` is mandatory, and `id` is a keyword, _not_ a field name!
- If collection's PK has more than one path (i.e. sub-partition is used), the partition paths must be specified in the same order as in the collection (.e.g. `AND pkfield1=value1 AND pkfield2=value2...`).
- `id-value` and `pk-value` must follow the value syntax described [here](#value). Note: value for `id` should always be a string!
- `DELETE` removes _only one document_ specified by `id`.
- Upon successful execution, `RowsAffected()` returns `(1, nil)`. If no document matched, `RowsAffected()` returns `(0, nil)`.
- `<id-value>` is treated as string, i.e. `WHERE id=abc` has the same effect as `WHERE id="abc"`. A placeholder can be used in the place of `<id-value>`. See [here](#value) for more details on values and placeholders.

> `gocosmos` automatically discovers PK of the collection by fetching metadata from server.
> Supplying pk-fields and pk-values is highly recommended to save one round-trip to server to fetch the collection's partition key info.
**Since <<VERSION>>**:

- `WITH SINGLE_PK` is deprecated and will be _removed_ in future version! Instead, use `AND pkfield=value` (or `AND pkfield1=value1 AND pkfield2=value2...` if [Hierarchical Partition Keys](https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys) - also known as sub-partitions - is used on the collection).
- Supplying values for partition key at the end of parameter list is no longer required, but still supported for backward compatibility. This behaviour will be _removed_ in future version!

[Back to top](#top)

Expand All @@ -396,17 +437,15 @@ Syntax:
UPDATE [<db-name>.]<collection-name>
SET <fiel1>=<value1>[,<field2>=<value2>,...<fieldN>=<valueN>]
WHERE id=<id-value>
[WITH singlePK|SINGLE_PK[=true]]
[AND pkfield1=<pk1-value> [AND pkfield2=<pk2-value> ...]]
```

> `<db-name>` can be omitted if `DefaultDb` is supplied in the Data Source Name (DSN).
`gocosmos` supports [Hierarchical Partition Keys](https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys) (or sub-partitions). If the collection is known not to have sub-partitions, supplying `WITH singlePK` (or `WITH SINGLE_PK`) can save one roundtrip to Cosmos DB server.

Example:
```go
sql := `UPDATE mydb.mytable SET a=1, b="\"a string\"", c=true, d="[1,true,null,\"string\"]", e=:2 WHERE id=@1`
dbresult, err := db.Exec(sql, "myid", map[string]interface{}{"key":"value"}, "mypk")
sql := `UPDATE mydb.mytable SET a=1, b="\"a string\"", c=true, d="[1,true,null,\"string\"]", e=:2 WHERE id=@1 AND pk=$3`
dbresult, err := db.Exec(sql, "myid", map[string]interface{}{"key":"value"}, "mypk") // note: id is $1 and value for field e is :2
if err != nil {
panic(err)
}
Expand All @@ -415,12 +454,19 @@ fmt.Println(dbresult.RowsAffected())

> Use `sql.DB.Exec` to execute the statement, `Query` will return error.
> Values of partition keys _must_ be supplied at the end of the argument list when invoking `db.Exec()`.
- `UPDATE` modifies only one document specified by id.
- The clause `WHERE id=<id-value>` is mandatory, and `id` is a keyword, _not_ a field name!
- If collection's PK has more than one path (i.e. sub-partition is used), the partition paths must be specified in the same order as in the collection (.e.g. `AND pkfield1=value1 AND pkfield2=value2...`).
- `id-value` and `pk-value` must follow the value syntax described [here](#value). Note: value for `id` should always be a string!
- `UPDATE` modifies _only one document_ specified by `id`.
- Upon successful execution, `RowsAffected()` returns `(1, nil)`. If no document matched, `RowsAffected()` returns `(0, nil)`.
- `<id-value>` is treated as string, i.e. `WHERE id=abc` has the same effect as `WHERE id="abc"`. A placeholder can be used in the place of `<id-value>`.
- See [here](#value) for more details on values and placeholders.

> `gocosmos` automatically discovers PK of the collection by fetching metadata from server.
> Supplying pk-fields and pk-values is highly recommended to save one round-trip to server to fetch the collection's partition key info.
**Since <<VERSION>>**:

- `WITH SINGLE_PK` is deprecated and will be _removed_ in future version! Instead, use `AND pkfield=value` (or `AND pkfield1=value1 AND pkfield2=value2...` if [Hierarchical Partition Keys](https://learn.microsoft.com/en-us/azure/cosmos-db/hierarchical-partition-keys) - also known as sub-partitions - is used on the collection).
- Supplying values for partition key at the end of parameter list is no longer required, but still supported for backward compatibility. This behaviour will be _removed_ in future version!

[Back to top](#top)

Expand Down

0 comments on commit 5b11c91

Please sign in to comment.