@gsb-core/mcp-docs
Version:
Documentation for GSB MCP implementations
263 lines (229 loc) • 8.22 kB
JavaScript
/**
* Documentation for the saveMulti operation
*/
/**
* Returns documentation for the saveMulti operation
* @return {string} markdown documentation
*/
export function saveMultiDocs() {
return `
# SaveMulti Operation
## General Description
The \`saveMulti\` operation saves multiple entities of the same type in a single operation, improving performance for batch operations.
## Detailed Description
This operation allows you to create or update multiple entities of the same type in a single database operation. It's more efficient than making multiple individual save calls, especially when dealing with large batches of data. Like the save operation, it handles both creating new entities and updating existing ones based on whether each entity has an ID.
Similar to the save operation, saveMulti supports complex JSON structures with nested objects and arrays. GSB automatically processes related entities, performing inserts or updates for all nested data and managing relationships based on the presence of primary keys.
## Input Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| request | object | Yes | The save request object containing the entities to save. |
| request.entityDef | object | Yes | The entity definition object with id and/or name properties. |
| request.entityDef.name | string | Yes* | Name of the entity definition. Required if entDefId is not provided. |
| request.entityDef.id | string | Yes* | ID of the entity definition. Required if entDefName is not provided. |
| request.entities | array | Yes | Array of entity objects to save. Each entity can have an ID (for update) or not (for create), and can include complex nested objects and arrays for related entities. |
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |
## Response
### Success Response
\`\`\`json
{
"success": true,
"ids": [
"string", // ID of the first saved entity
"string", // ID of the second saved entity
// Additional IDs in the same order as the input entities
]
}
\`\`\`
### Error Response
\`\`\`json
{
"success": false,
"message": "Error message describing what went wrong"
}
\`\`\`
## Example Usage
### Creating Multiple New Entities
\`\`\`typescript
const result = await saveMulti({
request: {
entDefName: "Product",
entities: [
{
name: "Product 1",
price: 10.99,
inStock: true
},
{
name: "Product 2",
price: 20.99,
inStock: false
},
{
name: "Product 3",
price: 15.49,
inStock: true
}
]
}
});
if (result.success) {
const savedIds = result.ids;
console.log(\`Successfully saved \${savedIds.length} products\`);
console.log("First product ID:", savedIds[0]);
console.log("Second product ID:", savedIds[1]);
} else {
console.error("Error:", result.error);
}
\`\`\`
### Mixing Creates and Updates
\`\`\`typescript
const result = await saveMulti({
request: {
entDefName: "Product",
entities: [
{
// New product (no ID)
name: "New Product",
price: 29.99,
inStock: true
},
{
// Existing product (has ID)
id: "existing-product-id",
name: "Updated Product Name",
price: 19.99,
inStock: false
}
]
}
});
if (result.success) {
console.log("Saved entity IDs:", result.ids);
// First ID is for the new product, second ID is the existing ID
}
\`\`\`
### Saving Entities with Complex Nested Data
\`\`\`typescript
const result = await saveMulti({
request: {
entDefName: "Order",
entities: [
{
orderNumber: "ORD-12345",
status: "pending",
customer: {
id: "customer-123", // Existing customer - will be updated
name: "John Doe",
email: "john@example.com"
},
items: [
{
productName: "Laptop",
quantity: 1,
unitPrice: 1299.99
},
{
productName: "Mouse",
quantity: 1,
unitPrice: 49.99
}
]
},
{
orderNumber: "ORD-67890",
status: "processing",
customer: {
// No ID - new customer will be created
name: "Jane Smith",
email: "jane@example.com"
},
items: [
{
id: "existing-item-456", // Existing item - will be updated
productName: "Headphones",
quantity: 1,
unitPrice: 199.99
}
]
}
]
}
});
if (result.success) {
console.log("Saved order IDs:", result.ids);
// Both orders and all their related entities are saved in a single transaction
}
\`\`\`
### Using Entity Definition ID
\`\`\`typescript
const result = await saveMulti({
request: {
entDefId: "product-definition-id",
entities: [
{
name: "Product A",
price: 9.99,
inStock: true
},
{
name: "Product B",
price: 14.99,
inStock: true
}
]
}
});
if (result.success) {
console.log("Saved entity IDs:", result.ids);
}
\`\`\`
## Additional Information
- All entities in a single saveMulti operation must be of the same type (same entity definition).
- The operation is transactional - either all entities are saved successfully, or none are.
- For each entity, the system automatically handles:
- Generating IDs for new entities
- Setting createDate and createdBy for new entities
- Updating lastUpdateDate and lastUpdatedBy for existing entities
- Required fields as defined in the entity definition must be provided for each entity.
- Validation rules defined in the entity definition are enforced for each entity.
- The operation returns an array of IDs for all saved entities, in the same order as the input entities.
- If any entity fails validation, the entire operation fails.
- For better performance, batch your saves into reasonably sized groups (e.g., 100-500 entities per call).
- For saving a single entity, use the save operation instead.
- For saving mapped items in a many-to-many relationship, use the saveMappedItems operation instead.
### Complex Data Handling
- Each entity in the entities array can include complex nested objects and arrays.
- GSB automatically processes nested objects and arrays as related entities.
- For each nested entity:
- If an ID is provided and exists in the database, the entity will be updated.
- If no ID is provided or the ID doesn't exist, a new entity will be created.
- Relationships between entities are automatically maintained.
- One-to-many and many-to-many relationships are handled through arrays of objects.
- One-to-one relationships are handled through nested objects.
- The system intelligently determines whether to perform inserts or updates based on the presence of primary keys.
- All operations are performed in a single transaction, ensuring data consistency across all entities and their related data.
- If any part of the complex save operation fails, the entire transaction is rolled back.
`;
}
/**
* Returns a brief summary of the saveMulti operation.
* @return {string} A short description of the function.
*/
export function saveMultiSummary() {
return `
**Purpose**: Creates or updates multiple entities in a single transaction.
**When to use**:
- Batch processing multiple entities
- Need better performance than individual saves
- Ensuring all-or-nothing transactions
**Inputs**:
- request: { entityDef:{ name: string, id: string }, entities: [...,{}]}//provide etiher name or id of the entity definition
- token (optional)
- tenantCode (optional)
**Returns**: IDs of all saved entities.
**Effects**: Creates/updates multiple database records atomically.
`;
}
export default saveMultiDocs;
//# sourceMappingURL=saveMulti.js.map