Bulk Operations

Bulk editing helpers from annnet.core._BulkOps.

annnet.core._BulkOps.BulkOps

Functions

add_vertices_bulk(vertices, slice=None)

Bulk add vertices with a Polars fast path when available.

Parameters:

Name	Type	Description	Default
vertices	Iterable[str] | Iterable[tuple[str, dict]] | Iterable[dict]	Vertices to add. Each item can be: - vertex_id (str) - (vertex_id, attrs) tuple - dict containing vertex_id plus attributes	required
slice	str	Target slice. Defaults to the active slice.	None

Returns:

Type	Description
None

Notes

Falls back to Narwhals-based logic when Polars is unavailable.

add_vertices_bulk_nw(vertices, slice=None)

Bulk add vertices using Narwhals-compatible operations.

Parameters:

Name	Type	Description	Default
vertices	Iterable[str] | Iterable[tuple[str, dict]] | Iterable[dict]	Vertices to add.	required
slice	str	Target slice. Defaults to the active slice.	None

Returns:

Type	Description
None

Notes

This path is slower than the Polars fast path but preserves behavior.

add_edges_bulk(edges, *, slice=None, default_weight=1.0, default_edge_type='regular', default_propagate='none', default_slice_weight=None, default_edge_directed=None)

Bulk add or update binary edges (and vertex-edge edges).

Parameters:

Name	Type	Description	Default
edges	Iterable	Each item can be: - (source, target) - (source, target, weight) - dict with keys source, target, and optional edge fields.	required
slice	str	Default slice to place edges into.	None
default_weight	float	Default weight for edges missing an explicit weight.	1.0
default_edge_type	str	Default edge type when not provided.	'regular'
default_propagate	(none, shared, all)	Default slice propagation mode.	'none'
default_slice_weight	float	Default per-slice weight override.	None
default_edge_directed	bool	Default per-edge directedness override.	None

Returns:

Type	Description
list[str]	Edge IDs for created/updated edges.

Notes

Behavior mirrors add_edge() but grows the matrix once to reduce overhead.

add_hyperedges_bulk(hyperedges, *, slice=None, default_weight=1.0, default_edge_directed=None)

Bulk add or update hyperedges.

Parameters:

Name	Type	Description	Default
hyperedges	Iterable[dict]	Each item can be: - {'members': [...], 'edge_id': ..., 'weight': ..., 'slice': ..., 'attributes': {...}} - {'head': [...], 'tail': [...], ...}	required
slice	str	Default slice for hyperedges missing an explicit slice.	None
default_weight	float	Default weight for hyperedges missing an explicit weight.	1.0
default_edge_directed	bool	Default directedness override.	None

Returns:

Type	Description
list[str]	Hyperedge IDs for created/updated hyperedges.

Notes

Behavior mirrors add_hyperedge() but grows the matrix once to reduce overhead.

add_edges_to_slice_bulk(slice_id, edge_ids)

Add many edges to a slice and attach all incident vertices.

Parameters:

Name	Type	Description	Default
slice_id	str	Slice identifier.	required
edge_ids	Iterable[str]	Edge identifiers to add.	required

Returns:

Type	Description
None

Notes

No weights are changed in this operation.

add_edge_entities_bulk(items, slice=None)

Bulk add edge-entities (vertex-edge hybrids).

Parameters:

Name	Type	Description	Default
items	Iterable	Accepts: - iterable of string IDs - iterable of (edge_entity_id, attrs) tuples - iterable of dicts with key edge_entity_id (or id)	required
slice	str	Target slice. Defaults to the active slice.	None

Returns:

Type	Description
None

Notes

Attribute inserts are batched for efficiency.

set_vertex_key(*fields)

Declare composite key fields and rebuild the uniqueness index.

Parameters:

Name	Type	Description	Default
*fields	str	Ordered field names used to build a composite key.	()

Raises:

Type	Description
ValueError	If duplicates exist among already-populated vertices.

Notes

Vertices missing some key fields are skipped during indexing.

remove_edges(edge_ids)

Remove many edges in one pass.

Parameters:

Name	Type	Description	Default
edge_ids	Iterable[str]	Edge identifiers to remove.	required

Returns:

Type	Description
None

Notes

This is faster than calling remove_edge in a loop.

remove_vertices(vertex_ids)

Remove many vertices (and their incident edges) in one pass.

Parameters:

Name	Type	Description	Default
vertex_ids	Iterable[str]	Vertex identifiers to remove.	required

Returns:

Type	Description
None

Notes

This is faster than calling remove_vertex in a loop.