Skip to content

Commit

Permalink
Editorial updates to the API (infiniflow#1560)
Browse files Browse the repository at this point in the history 
### What problem does this PR solve?

Issue link:infiniflow#1490

### Type of change


- [x] Documentation Update
  • Loading branch information
@writinwaters
writinwaters authored Jul 30, 2024
1 parent b2aed50 commit 6b52aa8
Showing 1 changed file with 114 additions and 30 deletions.
144 changes: 114 additions & 30 deletions docs/references/pysdk_api_reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The `uri` here can be either a `NetworkAddress` object or a local directory in `
- `"<SERVER_IP_ADDRESS>"` (`str`): The IP address of the Infinity server.
- `<PORT>` (`int`): The port number on which Infinity is running. Defaults to 23817.

:::alert IMPORTANT
:::caution IMPORTANT
When connecting to Infinity in a client-server mode, ensure that the version of the client exactly matches the version of the server. For example:

| **Client version** | **Server version** |
Expand Down Expand Up @@ -103,25 +103,59 @@ infinity_obj.disconnect()
Infinity.create_database(db_name, conflict_type = ConflictType.Error)
```

Creates a database with a given name. `conflict_type` specifies the policy when a database with the same name exists.
Creates a database with a specified name.

### Parameters

- **db_name : str(not empty)** Name of the database.
- **conflict_type : ConflictType** `enum` The countermeasure to take when a database with the same name exists. See `ConflictType`, which is defined in the **infinity.common** package:
- `Error`
- `Ignore`
#### db_name: `str`, *Required*

Name of the database. Must not be empty.

#### conflict_type: `ConflictType`, *Optional*

Conflict policy in `enum` for handling situations where a database with the same name exists.

- `Error`: Raise an error if a database with the same name exists.
- `Ignore`: Ignore the table creation requrest and keep the database with the same name as-is.

:::tip NOTE
You must import the `infinity.common` package to set `ConflictType`:

```python
from infinity.common import ConflictType
```
:::

:::tip NOTE
If `ConflictType` is not set, it defaults to `Error`.
:::

### Returns

- Success: `True`
- Failure: `Exception`

### Examples

```python
# Create a database named 'my_database':
# If the specified database already exists, raise an error.
infinity_obj.create_database("my_database")
```

```python
# Create a database named 'my_database':
# If the specified database already exists, raise an error (same as above).
infinity_obj.create_database("my_database", infinity.common.ConflictType.Error)
```

```python
from infinity.common import ConflictType
# Create a database named 'my_database':
# If the specified database already exists, silently ignore the operation and proceed.
infinity_obj.create_database("my_database", ConflictType.Ignore)
```

---

## drop_database
Expand All @@ -130,25 +164,59 @@ infinity_obj.create_database("my_database")
Infinity.drop_database(db_name, conflict_type = ConflictType.Error)
```

Drops a database by name.
Deletes a database by its name.

### Parameters

- `db_name`: `str` Name of the database
- `conflict_type`: `enum` Policy for handling an existing database with the same name. See `ConflictType`, which is defined in the **infinity.common** package.
- `Error`
- `Ignore`
#### db_name: `str`, *Required*

Name of the database to delete. Must not be empty.

#### conflict_type: `ConflictType`, *Optional*

Conflict policy in `enum` for handling situations where a database with the same name does not exist.

- `Error`: Raise an error if the specified database does not exist.
- `Ignore`: Ignore the operation and proceed regardless, if the specified database does not exist.

:::tip NOTE
You must import the `infinity.common` package to set `ConflictType`:

```python
from infinity.common import ConflictType
```
:::

:::tip NOTE
If `ConflictType` is not set, it defaults to `Error`.
:::

### Returns

- Success: `True`
- Failure: `Exception`

### Examples

```python
# Delete a database named 'my_database':
# If the specified database does not exist, raise an error.
infinity_obj.drop_database("my_database")
```

```python
# Delete a database named 'my_database':
# If the specified database does not exist, raise an error (same as above).
infinity_obj.drop_database("my_database", infinity.common.ConflictType.Error)
```

```python
from infinity.common import ConflictType
# Delete a database named 'my_database':
# If the specified database does not exist, silently ignore the operation and proceed.
infinity_obj.drop_database("my_database", ConflictType.Ignore)
```

---

## list_databases
Expand All @@ -157,18 +225,23 @@ infinity_obj.drop_database("my_database")
Infinity.list_databases()
```

Lists all databases.
Gets the names of all databases.

### Returns

- Success: `db_names` `list[str]`
- Failure: `Exception`
This method returns a structure containing the following attributes:

- `db_names`: `list[str]` A list of all database names.
- `error_code`: `int` An error code indicating the result of the operation.
- `0`: The operation succeeded.
- Non-zero value: A specific error condition occurred.
- `error_msg`: `str` The error message providing additional details.

### Examples

```python
res = infinity_obj.list_databases()
res.db_names #["my_database"]
print(res.db_names) #['my_database', 'database_1']
```

---
Expand All @@ -179,15 +252,17 @@ res.db_names #["my_database"]
Infinity.get_database(db_name)
```

Retrieves a database object by name.
Retrieves a database object by its name.

### Parameters

- `db_name`: `str` Name of the database.
#### db_name: `str`, *Required*

Name of the database. Must not be empty.

### Returns

- Success: A database object.
- Success: A database object.
- Failure: `Exception`

### Examples
Expand All @@ -204,15 +279,17 @@ db_obj=infinity_obj.get_database("my_database")
Infinity.show_database(db_name)
```

Retrieves the metadata of a database by name.
Retrieves the metadata of a database by its name.

### Parameters

- **db_name : str** Name of the database
#### db_name: `str`

Name of the database

### Returns

- Success: Metadata of the database. See the `ShowDatabaseResponse` struct, which includes:
- Success: Metadata of the database. See the `ShowDatabaseResponse` structure, which includes:
- `database_name`: `str` Name of the database.
- `store_dir`: `str` Directory to the database file.
- `table_count`: `int` Number of tables in the database.
Expand Down Expand Up @@ -254,10 +331,9 @@ Definitions for all table columns as a dictionary. Each key in the dictionary is

#### conflict_type: `ConflictType`, *Optional*

Conflict policy in `enum` for handling situations when a table with the same name exists.
Conflict policy in `enum` for handling situations where a table with the same name exists.
- `Error`: Raise an error if a table with the same name exists.
- `Ignore`: Ignore the table creation requrest and keep the table with the same name as-is.
- `Replace`: Drop the existing table and create a new one.

:::tip NOTE
You must import the `infinity.common` package to set `ConflictType`:
Expand Down Expand Up @@ -352,7 +428,7 @@ from infinity.common import ConflictType
# - `tensorarray`: The column is a tensor array column
# - `6`: Dimension of each vector unit in the tensor arrays
# - `float`: The primitive data type of the tensor arrays. Can be `float`/`float32` or `double`/`float64`
db_obj.create_table("my_table", {"c1": {"type": "tensorarray,6,float"}}, ConflictType.Replace)
db_obj.create_table("my_table", {"c1": {"type": "tensorarray,6,float"}}, ConflictType.Ignore)
```

---
Expand All @@ -372,7 +448,9 @@ Deletes a table from the database by its name.
Name of the table to delete. Must not be empty.

#### conflict_type: `ConflictType`, *Optional*
Conflict policy in `enum` for handling situations when a table with the same name does not exist.

Conflict policy in `enum` for handling situations where a table with the same name does not exist.

- `Error`: Raise an error if the specified table does not exist.
- `Ignore`: Ignore the operation and proceed regardless, if the specified table does not exist.

Expand All @@ -398,12 +476,18 @@ If `ConflictType` is not set, it defaults to `Error`.
```python
# Delete a table named 'my_table':
# If the specified table does not exist, raise an error.
db_obj.drop_table("my_table")
```

```python
# Delete a table named 'my_table':
# If the specified table does not exist, raise an error (same as above).
db_obj.drop_table("my_table", infinity.common.ConflictType.Error)
```

```python
from infinity.common import ConflictType
# Drop a table named 'my_table':
# Delete a table named 'my_table':
# If the specified table does not exist, silently ignore the operation and proceed.
db_obj.drop_table("my_table", ConflictType.Ignore)
```
Expand Down Expand Up @@ -516,13 +600,13 @@ Creates an index by `IndexInfo` list.

- **index_name : str**
- **index_infos : list[IndexInfo]**
A IndexInfo struct contains three fields,`column_name`, `index_type`, and `index_param_list`.
A IndexInfo structure contains three fields,`column_name`, `index_type`, and `index_param_list`.
- **column_name : str** Name of the column to build index on.
- **index_type : IndexType**
enum type: `IVFFlat` , `Hnsw`, `FullText`, or `BMP`. Defined in `infinity.index`.
`Note: For Hnsw index, add encode=lvq in index_param_list to use LVQ(Locally-adaptive vector quantization)`
- **index_param_list**
A list of InitParameter. The InitParameter struct is like a key-value pair, with two string fields named param_name and param_value. The optional parameters of each type of index are listed below:
A list of InitParameter. The InitParameter structure is like a key-value pair, with two string fields named param_name and param_value. The optional parameters of each type of index are listed below:
- `IVFFlat`: `'centroids_count'`(default:`'128'`), `'metric'`(required)
- `Hnsw`:
- `'M'`(default:`'16'`)
Expand Down Expand Up @@ -650,7 +734,7 @@ Retrieves the metadata of an index by name.
### Returns

- Success: `metadata` : `ShowIndexResponse`
the struct `ShowIndexResponse` contains:
the structure `ShowIndexResponse` contains:
- **db_name: string** Name of the database
- **table_name: string**
- **index_name: string**
Expand Down Expand Up @@ -1211,7 +1295,7 @@ Builds a fusion expression.

### Examples

:::alert IMPORTANT
:::caution IMPORTANT
Ensure that you import the following when using `make_match_tensor_expr`:

```python
Expand Down

0 comments on commit 6b52aa8

Please sign in to comment.