The Vineyard Python client API provides programmatic access to the Vineyard in-memory data manager. It supports IPC (UNIX domain socket) and RPC (TCP) connections for storing, retrieving, and managing distributed in-memory objects. Key operations include put, get, delete, persist, and metadata inspection.
openapi: 3.1.0
info:
title: Vineyard Python Client API
description: >-
The Vineyard Python client API provides programmatic access to the Vineyard
in-memory immutable data manager (v6d), a CNCF project. Clients connect via
IPC (UNIX domain socket) for zero-copy local access or via RPC (TCP) for
remote access. The API supports storing, retrieving, naming, persisting, and
deleting distributed in-memory objects.
version: 0.19.0
contact:
name: Vineyard Community
url: https://v6d.io/
license:
name: Apache 2.0
url: https://github.com/v6d-io/v6d/blob/main/LICENSE
externalDocs:
description: Vineyard Python API Reference
url: https://v6d.io/notes/references/python-api.html
servers:
- url: ipc://{socket}
description: IPC socket connection (local zero-copy access)
variables:
socket:
default: /var/run/vineyard.sock
- url: tcp://{host}:{port}
description: RPC TCP connection (remote access)
variables:
host:
default: localhost
port:
default: '9600'
tags:
- name: Connection
description: Connect to and disconnect from a vineyard server
- name: Objects
description: Store and retrieve in-memory objects
- name: Metadata
description: Inspect and manage object metadata
- name: Names
description: Associate human-readable names with object IDs
- name: Blobs
description: Low-level blob storage operations
- name: Persistence
description: Persist objects for cross-instance visibility
paths:
/connect:
post:
operationId: connectToServer
summary: Connect to Server
description: >-
Establish a connection to a vineyard server via IPC socket or TCP endpoint.
Returns a client object (IPCClient or RPCClient) for subsequent operations.
tags:
- Connection
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
socket:
type: string
description: UNIX domain socket path for IPC connection
example: /var/run/vineyard.sock
host:
type: string
description: Hostname for RPC TCP connection
port:
type: integer
description: Port number for RPC TCP connection
example: 9600
responses:
'200':
description: Successfully connected to vineyard server
content:
application/json:
schema:
$ref: '#/components/schemas/ClientInfo'
'503':
description: Server unavailable or connection failed
/objects:
post:
operationId: putObject
summary: Put Object
description: >-
Store a Python object in vineyard. Returns the ObjectID for later retrieval.
Optionally persist the object for cross-instance visibility or associate a name.
tags:
- Objects
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PutObjectRequest'
responses:
'201':
description: Object stored successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectIDResponse'
'400':
description: Invalid object or unsupported type
/objects/{objectId}:
get:
operationId: getObject
summary: Get Object
description: >-
Retrieve a vineyard object by its ObjectID, deserializing it back to a Python value.
tags:
- Objects
parameters:
- name: objectId
in: path
required: true
description: The 64-bit unsigned integer ObjectID
schema:
type: string
- name: fetch
in: query
required: false
description: Whether to fetch remote objects via RPC if not local
schema:
type: boolean
default: false
responses:
'200':
description: Object retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectResponse'
'404':
description: Object not found
delete:
operationId: deleteObject
summary: Delete Object
description: Remove a vineyard object from memory by its ObjectID.
tags:
- Objects
parameters:
- name: objectId
in: path
required: true
description: The ObjectID to delete
schema:
type: string
- name: force
in: query
required: false
description: Force deletion even if the object is referenced
schema:
type: boolean
default: true
- name: deep
in: query
required: false
description: Recursively delete member objects
schema:
type: boolean
default: true
responses:
'204':
description: Object deleted successfully
'404':
description: Object not found
/objects/{objectId}/metadata:
get:
operationId: getObjectMetadata
summary: Get Object Metadata
description: >-
Fetch the metadata of a vineyard object, including typename, nbytes,
isglobal, islocal, and all custom key-value metadata properties.
tags:
- Metadata
parameters:
- name: objectId
in: path
required: true
description: The ObjectID to inspect
schema:
type: string
responses:
'200':
description: Metadata retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectMetadata'
'404':
description: Object not found
/objects/{objectId}/persist:
post:
operationId: persistObject
summary: Persist Object
description: >-
Make a vineyard object persistent, making it visible across all vineyard
server instances in the cluster.
tags:
- Persistence
parameters:
- name: objectId
in: path
required: true
description: The ObjectID to persist
schema:
type: string
responses:
'200':
description: Object persisted successfully
'404':
description: Object not found
/names:
post:
operationId: putName
summary: Associate Name with Object
description: Associate a human-readable name string with a vineyard ObjectID.
tags:
- Names
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- object_id
- name
properties:
object_id:
type: string
description: The ObjectID to associate with the name
name:
type: string
description: Human-readable name string
responses:
'200':
description: Name associated successfully
'409':
description: Name already in use
/names/{name}:
get:
operationId: getByName
summary: Get Object by Name
description: Retrieve the ObjectID associated with a human-readable name.
tags:
- Names
parameters:
- name: name
in: path
required: true
description: The human-readable name
schema:
type: string
- name: wait
in: query
required: false
description: Block until the name becomes available
schema:
type: boolean
default: false
responses:
'200':
description: ObjectID retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectIDResponse'
'404':
description: Name not found
/blobs:
post:
operationId: createBlob
summary: Create Blob
description: Allocate a raw memory blob of the specified size in vineyard.
tags:
- Blobs
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- size
properties:
size:
type: integer
description: Number of bytes to allocate
responses:
'201':
description: Blob created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BlobInfo'
/blobs/{objectId}:
get:
operationId: getBlob
summary: Get Blob
description: Retrieve a raw memory blob by its ObjectID.
tags:
- Blobs
parameters:
- name: objectId
in: path
required: true
schema:
type: string
- name: remote
in: query
required: false
description: Retrieve blob from a remote vineyard instance
schema:
type: boolean
default: false
responses:
'200':
description: Blob retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/BlobInfo'
'404':
description: Blob not found
components:
schemas:
ClientInfo:
type: object
description: Information about the established vineyard client connection
properties:
instance_id:
type: integer
description: The vineyard instance ID this client is connected to
version:
type: string
description: Vineyard server version
ipc_socket:
type: string
description: IPC socket path (for IPCClient)
rpc_endpoint:
type: string
description: RPC endpoint (for RPCClient)
PutObjectRequest:
type: object
description: Request to store an object in vineyard
properties:
value:
description: The Python object to store (serialized representation)
persist:
type: boolean
description: Whether to immediately persist the object globally
default: false
name:
type: string
description: Optional human-readable name to associate
ObjectIDResponse:
type: object
description: Response containing a vineyard ObjectID
properties:
object_id:
type: string
description: The 64-bit unsigned integer ObjectID as a string
ObjectResponse:
type: object
description: Response containing a retrieved vineyard object
properties:
object_id:
type: string
description: The ObjectID of the retrieved object
value:
description: The deserialized Python object value
typename:
type: string
description: The vineyard type name of the object
ObjectMetadata:
type: object
description: Metadata for a vineyard object
properties:
id:
type: string
description: The ObjectID
typename:
type: string
description: >-
Type name of the object (e.g., vineyard::Tensor<float64>,
vineyard::DataFrame, vineyard::RecordBatch)
nbytes:
type: integer
description: Memory size in bytes
isglobal:
type: boolean
description: Whether the object is globally persistent across instances
islocal:
type: boolean
description: Whether the object is local to this vineyard instance
instance_id:
type: integer
description: The vineyard instance ID where the object resides
hostname:
type: string
description: Hostname of the vineyard instance
extra:
type: object
description: Additional custom key-value metadata properties
additionalProperties:
type: string
BlobInfo:
type: object
description: Information about a raw vineyard blob
properties:
object_id:
type: string
description: The ObjectID of the blob
size:
type: integer
description: Size of the blob in bytes
buffer:
type: string
description: Base64-encoded blob data (for remote blobs)