Initial commit

2025-11-30 08:44:54 +08:00
commit eb309b7b59
133 changed files with 21979 additions and 0 deletions
--- a/skills/seekdb-docs/official-docs/200.develop/900.sdk/50.apis/300.dml/200.add-data-of-api.md
+++ b/skills/seekdb-docs/official-docs/200.develop/900.sdk/50.apis/300.dml/200.add-data-of-api.md
@@ -0,0 +1,117 @@
+---
+slug: /add-data-of-api
+---
+
+# add - Insert data
+
+The `add()` method inserts new data into a collection. If a record with the same ID already exists, an error is returned.
+
+:::info
+
+This API is only available when using a Client. For more information about the Client, see [Client](../50.client.md).
+
+:::
+
+## Prerequisites
+
+* You have installed pyseekdb. For more information about how to install pyseekdb, see [Quick Start](../../10.pyseekdb-sdk/10.pyseekdb-sdk-get-started.md).
+
+* You have connected to the database. For more information about how to connect to the database, see [Client](../50.client.md).
+
+* If you are using seekdb or OceanBase Database in client mode, make sure that the user to which you are connected has the `INSERT` privilege on the table to be operated. For more information about how to view the privileges of the current user, see [View user privileges](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000003980135). If you do not have the required privilege, contact the administrator to grant you the privilege. For more information about how to directly grant a privilege, see [Directly grant a privilege](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000003980140).
+
+## Request parameters
+
+```python
+add(
+    ids=ids,
+    embeddings=embeddings,
+    documents=documents,
+    metadatas=metadatas
+)
+```
+
+|Parameter|Type|Required|Description|Example value|
+|---|---|---|---|---|
+|`ids`|string or List[str]|Yes|The ID of the data to be inserted. You can specify a single ID or an array of IDs.|item1|
+|`embeddings`|List[float] or List[List[float]]|No|The vector or vectors of the data to be inserted. If you specify this parameter, the value of `embedding_function` is ignored. If you do not specify this parameter, you must specify `documents`, and the `collection` must have an `embedding_function`.|[0.1, 0.2, 0.3]|
+|`documents`|string or List[str]|No|The document or documents to be inserted. If you do not specify `vectors`, `documents` will be converted to vectors using the `embedding_function` of the `collection`.|"This is a document"|
+|`metadatas`|dict or List[dict]|No|The metadata or metadata list of the data to be inserted. |`{"category": "AI", "score": 95}`|
+
+:::info
+
+The `embedding_function` associated with the collection is set during `create_collection()` or `get_collection()`. You cannot override it for each operation.
+
+:::
+
+## Request example
+
+```python
+import pyseekdb
+from pyseekdb import DefaultEmbeddingFunction, HNSWConfiguration
+
+# Create a client
+client = pyseekdb.Client()
+
+collection = client.create_collection(
+    name="my_collection",
+    configuration=HNSWConfiguration(dimension=3, distance='cosine'),
+    embedding_function=None
+)
+
+# Add single item
+collection.add(
+    ids="item1",
+    embeddings=[0.1, 0.2, 0.3],
+    documents="This is a document",
+    metadatas={"category": "AI", "score": 95}
+)
+
+# Add multiple items
+collection.add(
+    ids=["item4", "item2", "item3"],
+    embeddings=[
+        [0.1, 0.2, 0.4],
+        [0.4, 0.5, 0.6],
+        [0.7, 0.8, 0.9]
+    ],
+    documents=[
+        "Document 1",
+        "Document 2",
+        "Document 3"
+    ],
+    metadatas=[
+        {"category": "AI", "score": 95},
+        {"category": "ML", "score": 88},
+        {"category": "DL", "score": 92}
+    ]
+)
+
+# Add with only embeddings
+collection.add(
+    ids=["vec1", "vec2"],
+    embeddings=[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
+)
+
+collection1 = client.create_collection(
+            name="my_collection1"
+            )
+
+# Add with only documents - embeddings auto-generated by embedding_function
+# Requires: collection must have embedding_function set
+collection1.add(
+    ids=["doc1", "doc2"],
+    documents=["Text document 1", "Text document 2"],
+    metadatas=[{"tag": "A"}, {"tag": "B"}]
+)
+```
+
+## Response parameters
+
+None
+
+## References
+
+* [Update data](300.update-data-of-api.md)
+* [Update or insert data](400.upsert-data-of-api.md)
+* [Delete data](500.delete-data-of-api.md)