feat: Add filtered collection truncate (#5097)

## Relevant issue(s)

Resolves #5117

## Description

Adds an optional filter to the existing collection truncate operation so
callers can permanently remove matching documents from the local node
without introducing another delete command. Truncating without a filter
keeps the existing collection-wide behavior.

Filtered truncate removes the selected document data and associated
local state, including heads, indexes, ID mappings, signatures,
encryption blocks, and searchable-encryption records. The optional
`pruneHistory` setting also removes history blocks that are not shared
by another document.

The filter is supported by the Go, HTTP, CLI, and C APIs, and GraphQL
now exposes `truncate_<Collection>` mutations. No new dependencies are
added.

Limitations:

- Truncate is local and does not replicate. Propagate soft-delete
tombstones first when peers must not reintroduce the data.
- History pruning is rejected for branchable collections until
collection-DAG pruning semantics are defined.
- Filtered truncate runs in bounded chunks and may be partially applied
if a later chunk fails.
- Filtered truncate cannot run inside a caller-supplied transaction.
GraphQL truncate must be a standalone mutation.

## Tasks

- [x] I made sure the code is well commented, particularly
hard-to-understand areas.
- [x] I made sure the repository-held documentation is changed
accordingly.
- [x] I made sure the pull request title adheres to the conventional
commit style (the subset used in the project can be found in
[tools/configs/chglog/config.yml](tools/configs/chglog/config.yml)).
- [x] I made sure to discuss its limitations such as threats to
validity, vulnerability to mistake and misuse, robustness to
invalidation of assumptions, resource requirements, ...

## How has this been tested?

- Unit coverage for filtering, storage cleanup, shared history, indexes,
ID mappings, signatures, encryption, searchable encryption, transaction
chunking, and LevelDB behavior.
- Integration coverage for collection and GraphQL truncate flows, DAC
authorization, and searchable encryption.
- Race tests for the changed database and GraphQL paths.
- Repository lint and generated documentation checks.

Specify the platform(s) on which this was tested:

- MacOS

Author: iverc

cbindings/collection_truncate.go

@@ -21,13 +21,49 @@ import (
 
 	"github.com/sourcenetwork/defradb/client/options"
 	acpIdentity "github.com/sourcenetwork/defradb/internal/identity"
+	"github.com/sourcenetwork/defradb/internal/utils"
 )
 
 //export TruncateCollection
 func TruncateCollection(
 	nodePtr C.uintptr_t,
 	opts C.CollectionOptions,
 	identityPtr C.uintptr_t,
+) C.Result {
+	return truncateCollection(nodePtr, opts, identityPtr, nil)
+}
+
+// TruncateCollectionWithFilter preserves TruncateCollection's v1 C ABI.
+//
+// Deprecated: This compatibility function will be removed in v2, when TruncateCollection
+// accepts filtered-truncate options.
+//
+//export TruncateCollectionWithFilter
+func TruncateCollectionWithFilter(
+	nodePtr C.uintptr_t,
+	opts C.CollectionOptions,
+	identityPtr C.uintptr_t,
+	filterJSON *C.char,
+) C.Result {
+	if filterJSON == nil {
+		return returnC(returnGoC(1, "filter is required", ""))
+	}
+	filter, err := utils.DecodeJSONFilter([]byte(C.GoString(filterJSON)))
+	if err != nil {
+		return returnC(returnGoC(1, err.Error(), ""))
+	}
+	// JSON null must not fall through to an unfiltered collection truncate.
+	if filter == nil {
+		return returnC(returnGoC(1, "filter cannot be null", ""))
+	}
+	return truncateCollection(nodePtr, opts, identityPtr, filter)
+}
+
+func truncateCollection(
+	nodePtr C.uintptr_t,
+	opts C.CollectionOptions,
+	identityPtr C.uintptr_t,
+	filter any,
 ) C.Result {
 	ctx := context.Background()
 
@@ -54,7 +90,11 @@ func TruncateCollection(
 		return returnC(returnGoC(1, err.Error(), ""))
 	}
 
-	err = col.Truncate(ctx, options.WithIdentity(options.TruncateCollection(), ident))
+	truncateOpts := options.WithIdentity(options.TruncateCollection(), ident)
+	if filter != nil {
+		truncateOpts.SetFilter(filter)
+	}
+	err = col.Truncate(ctx, truncateOpts)
 	if err != nil {
 		return returnC(returnGoC(1, err.Error(), ""))
 	}

cbindings/wrapper_collection.go

@@ -23,6 +23,8 @@ extern Result NewEncryptedIndex(uintptr_t nodePtr, char* collectionName, char* f
 extern Result ListEncryptedIndexes(uintptr_t nodePtr, char* collectionName, uintptr_t identityPtr);
 extern Result DeleteEncryptedIndex(uintptr_t nodePtr, char* collectionName, char* fieldName, uintptr_t identity);
 extern Result TruncateCollection(uintptr_t nodePtr, CollectionOptions options, uintptr_t identityPtr);
+extern Result TruncateCollectionWithFilter(uintptr_t nodePtr, CollectionOptions options, uintptr_t identityPtr,
+char* filterJSON);
 extern void FreeIdentity(uintptr_t identityPtr);
 */
 import "C"
@@ -311,11 +313,12 @@ func (c *Collection) Truncate(
 	ctx context.Context, opts ...options.Enumerable[options.TruncateCollectionOptions],
 ) error {
 	ctx = setCtxTxnFromCollection(ctx, c)
+	opt := utils.NewOptions(opts...)
 
 	cName := C.CString(c.def.Name)
 	cVersion := C.CString("")
 	cCollectionID := C.CString("")
-	cIdentity := optionToUintptr(utils.NewOptions(opts...).GetIdentity())
+	cIdentity := optionToUintptr(opt.GetIdentity())
 
 	defer C.free(unsafe.Pointer(cName))
 	defer C.free(unsafe.Pointer(cVersion))
@@ -329,13 +332,19 @@ func (c *Collection) Truncate(
 	copts.getInactive = 0
 
 	callHandle := getNodeOrTxnHandle(c.w.handle, ctx)
-	res := ConvertAndFreeCResult(
-		C.TruncateCollection(
-			callHandle,
-			copts,
-			cIdentity,
-		),
-	)
+	var result C.Result
+	if opt.Filter == nil {
+		result = C.TruncateCollection(callHandle, copts, cIdentity)
+	} else {
+		filterJSON, err := json.Marshal(opt.Filter)
+		if err != nil {
+			return err
+		}
+		cFilter := C.CString(string(filterJSON))
+		defer C.free(unsafe.Pointer(cFilter))
+		result = C.TruncateCollectionWithFilter(callHandle, copts, cIdentity, cFilter)
+	}
+	res := ConvertAndFreeCResult(result)
 	if res.Status != 0 {
 		return errors.New(res.Error)
 	}

cli/collection_truncate.go

@@ -12,20 +12,24 @@ package cli
 
 import (
 	"context"
+	"errors"
 
 	"github.com/spf13/cobra"
 
 	"github.com/sourcenetwork/defradb/client"
 	"github.com/sourcenetwork/defradb/client/options"
 	"github.com/sourcenetwork/defradb/internal/identity"
+	"github.com/sourcenetwork/defradb/internal/utils"
 )
 
 func MakeCollectionTruncateCommand(ctx context.Context) *cobra.Command {
+	var filter string
 	var cmd = &cobra.Command{
 		Use:   "truncate",
 		Short: "Truncate the given collection",
-		Long: `Truncate the given collection, removing all document data within it from the local node.
- Does not propagate the deletion to other Defra nodes in the peer network.`,
+		Long: `Truncate the given collection, removing document data from the local node.
+Without a filter all documents are removed. With a filter only matching documents and their
+unshared history are removed. Changes do not propagate to other nodes.`,
 		Args: cobra.ExactArgs(0),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			col, ok := tryGetContextCollection(cmd)
@@ -34,9 +38,28 @@ func MakeCollectionTruncateCommand(ctx context.Context) *cobra.Command {
 			}
 
 			opt := options.WithIdentity(options.TruncateCollection(), identity.FromContext(cmd.Context()))
+			if filter != "" {
+				filterValue, err := parseTruncateFilter(filter)
+				if err != nil {
+					return NewErrParsingArgument("filter", err)
+				}
+				opt.SetFilter(filterValue)
+			}
 			return col.Truncate(cmd.Context(), opt)
 		},
 	}
+	cmd.Flags().StringVar(&filter, "filter", "", "Document filter")
 	setCollectionSelectorFlags(cmd)
 	return cmd
 }
+
+func parseTruncateFilter(value string) (any, error) {
+	filter, err := utils.DecodeJSONFilter([]byte(value))
+	if err != nil {
+		return nil, err
+	}
+	if filter == nil {
+		return nil, errors.New("filter cannot be null")
+	}
+	return filter, nil
+}

cli/collection_truncate_test.go

@@ -0,0 +1,33 @@
+// Copyright 2026 Democratized Data Foundation
+//
+// Use of this software is governed by the Business Source License
+// included in the file licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with
+// the Business Source License, use of this software will be governed
+// by the Apache License, Version 2.0, included in the file
+// licenses/APL.txt.
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseTruncateFilter(t *testing.T) {
+	filter, err := parseTruncateFilter(`{"name":{"_eq":"Alice"}}`)
+	require.NoError(t, err)
+	require.Equal(t, map[string]any{"name": map[string]any{"_eq": "Alice"}}, filter)
+
+	filter, err = parseTruncateFilter(`{"age":{"_eq":9007199254740993}}`)
+	require.NoError(t, err)
+	require.Equal(t, map[string]any{"age": map[string]any{"_eq": int64(9007199254740993)}}, filter)
+
+	_, err = parseTruncateFilter("null")
+	require.EqualError(t, err, "filter cannot be null")
+
+	_, err = parseTruncateFilter("{")
+	require.Error(t, err)
+}

client/collection.go

@@ -59,12 +59,10 @@ type Collection interface {
 	// will be created.
 	SaveDocument(ctx context.Context, doc *Document, opts ...options.Enumerable[options.SaveDocumentOptions]) error
 
-	// DeleteDocument will attempt to delete a document by DocID.
+	// DeleteDocument soft-deletes a document by DocID and publishes the deletion for replication.
 	//
-	// Will return true if a deletion is successful, and return false along with an error
-	// if it cannot. If the document doesn't exist, then it will return false and a ErrDocumentNotFound error.
-	// This operation will hard-delete all state relating to the given DocID.
-	// This includes data, block, and head storage.
+	// The document data and commit history remain available locally. If the document does not exist,
+	// this returns false and an ErrDocumentNotFound error.
 	DeleteDocument(
 		ctx context.Context,
 		docID DocID,
@@ -167,7 +165,9 @@ type Collection interface {
 		opts ...options.Enumerable[options.ListCollectionEncryptedIndexesOptions],
 	) ([]EncryptedIndexDescription, error)
 
-	// Truncate this collection, permanently deleting all document state on this node.
+	// Truncate permanently deletes document state from this collection on this node.
+	// Set a filter in the options to target matching documents; without one, all document state is deleted.
+	// Filtered truncation can also remove unshared document history.
 	//
 	// Changes made by this call will not impact other nodes, and cannot be synced to them over the P2P
 	// system.

client/options/collection.go

@@ -410,6 +410,8 @@ func (b *ExistsDocumentOptionsBuilder) SetIdentity(id identity.Identity) *Exists
 type TruncateCollectionOptions struct {
 	// Identity is the identity of the actor performing the operation.
 	Identity immutable.Option[identity.Identity]
+	// Filter limits the truncate to matching documents. A nil filter truncates the full collection.
+	Filter any
 }
 
 // GetIdentity returns the identity for the operation.
@@ -435,6 +437,14 @@ func (b *TruncateCollectionOptionsBuilder) SetIdentity(id identity.Identity) *Tr
 	return b
 }
 
+// SetFilter limits the truncate to matching documents.
+func (b *TruncateCollectionOptionsBuilder) SetFilter(filter any) *TruncateCollectionOptionsBuilder {
+	b.append(func(opts *TruncateCollectionOptions) {
+		opts.Filter = filter
+	})
+	return b
+}
+
 // NewEncryptedIndexOptions contains options for NewEncryptedIndex operation.
 type NewEncryptedIndexOptions struct {
 	Identity immutable.Option[identity.Identity]

client/request/mutation.go

@@ -18,6 +18,7 @@ const (
 	UpdateObjects
 	DeleteObjects
 	UpsertObjects
+	TruncateObjects
 )
 
 // ObjectMutation is a field on the `mutation` operation of a graphql request. It includes

docs/website/references/cli/defradb_client_collection_truncate.md

@@ -4,8 +4,9 @@ Truncate the given collection
 
 ### Synopsis
 
-Truncate the given collection, removing all document data within it from the local node.
- Does not propagate the deletion to other Defra nodes in the peer network.
+Truncate the given collection, removing document data from the local node.
+Without a filter all documents are removed. With a filter only matching documents and their
+unshared history are removed. Changes do not propagate to other nodes.
 
 ```
 defradb client collection truncate [flags]
@@ -16,6 +17,7 @@ defradb client collection truncate [flags]
 ```
       --collection-id string     Collection ID
       --collection-name string   Collection name
+      --filter string            Document filter
       --get-inactive             Get inactive collections as well as active
   -h, --help                     help for truncate
       --version-id string        Collection version ID

docs/website/references/http/openapi.json

@@ -677,6 +677,12 @@
                 },
                 "type": "object"
             },
+            "truncate_collection": {
+                "properties": {
+                    "filter": {}
+                },
+                "type": "object"
+            },
             "update_collection": {
                 "properties": {
                     "filter": {},
@@ -1925,7 +1931,7 @@
         },
         "/collections/{name}/truncate": {
             "delete": {
-                "description": "Truncate a collection, removing all document data within it from the server. Does not propagate the deletion to other Defra nodes in the network.",
+                "description": "Permanently remove all or filtered document data from a collection on this server. Does not propagate the deletion to other Defra nodes in the network.",
                 "operationId": "truncate",
                 "parameters": [
                     {
@@ -1938,6 +1944,15 @@
                         }
                     }
                 ],
+                "requestBody": {
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/truncate_collection"
+                            }
+                        }
+                    }
+                },
                 "responses": {
                     "200": {
                         "$ref": "#/components/responses/success"

http/client_collection.go

@@ -212,7 +212,20 @@ func (c *Collection) Truncate(
 
 	methodURL := c.http.apiURL.JoinPath("collections", c.Version().Name, "truncate")
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, methodURL.String(), nil)
+	var body *bytes.Buffer
+	if opt.Filter != nil {
+		data, err := json.Marshal(TruncateCollectionRequest{
+			Filter: opt.Filter,
+		})
+		if err != nil {
+			return err
+		}
+		body = bytes.NewBuffer(data)
+	} else {
+		body = bytes.NewBuffer(nil)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, methodURL.String(), body)
 	if err != nil {
 		return err
 	}