feat: better search

Taskfile.yml

@@ -111,6 +111,23 @@ tasks:
     cmds:
       - go test {{ .CLI_ARGS }} ./...
 
+  go:test:meilisearch:
+    desc: Runs the Meilisearch search engine integration tests against a dockerized instance
+    dir: backend
+    cmds:
+      - docker run -d --rm --name homebox-meili-test -p 7711:7700 -e MEILI_MASTER_KEY=test-master-key -e MEILI_NO_ANALYTICS=true getmeili/meilisearch:v1.22
+      - defer: docker stop homebox-meili-test
+      - |
+        i=0
+        while [ "$i" -lt 60 ]; do
+          if curl -sf http://localhost:7711/health > /dev/null; then exit 0; fi
+          i=$((i + 1))
+          sleep 0.5
+        done
+        echo "Meilisearch did not become healthy within 30s" >&2
+        exit 1
+      - TEST_MEILISEARCH_URL=http://localhost:7711 TEST_MEILISEARCH_KEY=test-master-key go test ./internal/data/search/ -v -count=1
+
   go:coverage:
     desc: Runs all go tests with -race flag and generates a coverage report
     dir: backend

backend/app/api/cli_reset_password.go

@@ -118,7 +118,7 @@ func generateResetLinkOffline(cfg *config.Config, email string) (string, error)
 	}
 
 	bus := eventbus.New()
-	repos := repo.New(c, bus, cfg.Storage, cfg.Database.PubSubConnString, cfg.Thumbnail)
+	repos := repo.New(c, bus, cfg.Storage, cfg.Database.PubSubConnString, cfg.Thumbnail, nil)
 	svc := services.New(repos)
 
 	baseURL := strings.TrimSuffix(cfg.Options.Hostname, "/")

backend/app/api/handlers/v1/v1_ctrl_entities.go

@@ -48,12 +48,13 @@
 //	@Summary	Query All Entities
 //	@Tags		Entities
 //	@Produce	json
-//	@Param		q			query		string		false	"search string"
-//	@Param		page		query		int			false	"page number"
-//	@Param		pageSize	query		int			false	"items per page"
-//	@Param		tags		query		[]string	false	"tags Ids"		collectionFormat(multi)
-//	@Param		parentIds	query		[]string	false	"parent Ids"	collectionFormat(multi)
-//	@Success	200			{object}	repo.EntityListResult
+//	@Param		q				query		string		false	"search string; matches names, descriptions, serial/model numbers, manufacturers, notes, purchase sources, tag names, and custom field values. Use #<assetId> to look up by asset ID and double quotes for exact phrases"
+//	@Param		page			query		int			false	"page number"
+//	@Param		pageSize		query		int			false	"items per page"
+//	@Param		tags			query		[]string	false	"tags Ids"		collectionFormat(multi)
+//	@Param		matchAllTags	query		bool		false	"require all selected tags to match (AND) instead of any (OR)"
+//	@Param		parentIds		query		[]string	false	"parent Ids"	collectionFormat(multi)
+//	@Success	200				{object}	repo.EntityListResult
 //	@Router		/v1/entities [GET]
 //	@Security	Bearer
 func (ctrl *V1Controller) HandleEntitiesGetAll() errchain.HandlerFunc {
@@ -80,6 +81,7 @@
 			ParentIDs:        queryUUIDList(params, "parentIds"),
 			TagIDs:           queryUUIDList(params, "tags"),
 			NegateTags:       queryBool(params.Get("negateTags")),
+			MatchAllTags:     queryBool(params.Get("matchAllTags")),
 			OnlyWithoutPhoto: queryBool(params.Get("onlyWithoutPhoto")),
 			OnlyWithPhoto:    queryBool(params.Get("onlyWithPhoto")),
 			IncludeArchived:  queryBool(params.Get("includeArchived")),
@@ -582,4 +584,4 @@
 		}
 		return nil
 	}
 }

backend/app/api/main.go

@@ -16,6 +16,7 @@ import (
 	"github.com/sysadminsmedia/homebox/backend/internal/core/services/reporting/eventbus"
 	"github.com/sysadminsmedia/homebox/backend/internal/data/ent"
 	"github.com/sysadminsmedia/homebox/backend/internal/data/repo"
+	"github.com/sysadminsmedia/homebox/backend/internal/data/search"
 	"github.com/sysadminsmedia/homebox/backend/internal/sys/analytics"
 	"github.com/sysadminsmedia/homebox/backend/internal/sys/config"
 	"github.com/sysadminsmedia/homebox/backend/internal/sys/otel"
@@ -162,7 +163,13 @@ func run(cfg *config.Config) error {
 
 	app.bus = eventbus.New()
 	app.db = c
-	app.repos = repo.New(c, app.bus, cfg.Storage, cfg.Database.PubSubConnString, cfg.Thumbnail)
+
+	searchEngine, err := search.NewEngine(cfg.Search, c, app.bus)
+	if err != nil {
+		log.Error().Err(err).Str("driver", cfg.Search.Driver).Msg("failed to create search engine")
+		return err
+	}
+	app.repos = repo.New(c, app.bus, cfg.Storage, cfg.Database.PubSubConnString, cfg.Thumbnail, searchEngine)
 
 	// Attachment-key escaping in fileblob only flattens paths on Windows
 	// (where os.PathSeparator is "\"), so the legacy-path rename is a Windows-

backend/app/api/static/docs/docs.go

@@ -247,7 +247,7 @@ const docTemplate = `{
                 "parameters": [
                     {
                         "type": "string",
-                        "description": "search string",
+                        "description": "search string; matches names, descriptions, serial/model numbers, manufacturers, notes, purchase sources, tag names, and custom field values. Use #\u003cassetId\u003e to look up by asset ID and double quotes for exact phrases",
                         "name": "q",
                         "in": "query"
                     },
@@ -273,6 +273,12 @@ const docTemplate = `{
                         "name": "tags",
                         "in": "query"
                     },
+                    {
+                        "type": "boolean",
+                        "description": "require all selected tags to match (AND) instead of any (OR)",
+                        "name": "matchAllTags",
+                        "in": "query"
+                    },
                     {
                         "type": "array",
                         "items": {

backend/app/api/static/docs/openapi-3.json

@@ -245,7 +245,7 @@
                 "summary": "Query All Entities",
                 "parameters": [
                     {
-                        "description": "search string",
+                        "description": "search string; matches names, descriptions, serial/model numbers, manufacturers, notes, purchase sources, tag names, and custom field values. Use #<assetId> to look up by asset ID and double quotes for exact phrases",
                         "name": "q",
                         "in": "query",
                         "schema": {
@@ -280,6 +280,14 @@
                             }
                         }
                     },
+                    {
+                        "description": "require all selected tags to match (AND) instead of any (OR)",
+                        "name": "matchAllTags",
+                        "in": "query",
+                        "schema": {
+                            "type": "boolean"
+                        }
+                    },
                     {
                         "description": "parent Ids",
                         "name": "parentIds",

backend/app/api/static/docs/openapi-3.yaml

@@ -144,7 +144,10 @@ paths:
         - Entities
       summary: Query All Entities
       parameters:
-        - description: search string
+        - description: "search string; matches names, descriptions, serial/model numbers,
+            manufacturers, notes, purchase sources, tag names, and custom field
+            values. Use #<assetId> to look up by asset ID and double quotes for
+            exact phrases"
           name: q
           in: query
           schema:
@@ -167,6 +170,11 @@ paths:
             type: array
             items:
               type: string
+        - description: require all selected tags to match (AND) instead of any (OR)
+          name: matchAllTags
+          in: query
+          schema:
+            type: boolean
         - description: parent Ids
           name: parentIds
           in: query

backend/app/api/static/docs/swagger.json

@@ -244,7 +244,7 @@
                 "parameters": [
                     {
                         "type": "string",
-                        "description": "search string",
+                        "description": "search string; matches names, descriptions, serial/model numbers, manufacturers, notes, purchase sources, tag names, and custom field values. Use #\u003cassetId\u003e to look up by asset ID and double quotes for exact phrases",
                         "name": "q",
                         "in": "query"
                     },
@@ -270,6 +270,12 @@
                         "name": "tags",
                         "in": "query"
                     },
+                    {
+                        "type": "boolean",
+                        "description": "require all selected tags to match (AND) instead of any (OR)",
+                        "name": "matchAllTags",
+                        "in": "query"
+                    },
                     {
                         "type": "array",
                         "items": {

backend/app/api/static/docs/swagger.yaml

@@ -2479,7 +2479,9 @@ paths:
   /v1/entities:
     get:
       parameters:
-      - description: search string
+      - description: 'search string; matches names, descriptions, serial/model numbers,
+          manufacturers, notes, purchase sources, tag names, and custom field values.
+          Use #<assetId> to look up by asset ID and double quotes for exact phrases'
         in: query
         name: q
         type: string
@@ -2498,6 +2500,10 @@ paths:
           type: string
         name: tags
         type: array
+      - description: require all selected tags to match (AND) instead of any (OR)
+        in: query
+        name: matchAllTags
+        type: boolean
       - collectionFormat: multi
         description: parent Ids
         in: query

backend/go.mod

@@ -21,6 +21,7 @@ require (
 	github.com/gorilla/schema v1.4.1
 	github.com/hay-kot/httpkit v0.0.11
 	github.com/jackc/pgx/v5 v5.10.0
+	github.com/meilisearch/meilisearch-go v0.36.3
 	github.com/olahol/melody v1.4.0
 	github.com/pkg/errors v0.9.1
 	github.com/pressly/goose/v3 v3.27.1
@@ -95,6 +96,7 @@ require (
 	github.com/IBM/sarama v1.50.2 // indirect
 	github.com/KyleBanks/depth v1.2.1 // indirect
 	github.com/agext/levenshtein v1.2.3 // indirect
+	github.com/andybalholm/brotli v1.2.1 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
 	github.com/aws/aws-sdk-go-v2 v1.41.9 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.11 // indirect

backend/go.sum

@@ -79,6 +79,8 @@ github.com/XSAM/otelsql v0.42.0 h1:Li0xF4eJUxG2e0x3D4rvRlys1f27yJKvjTh7ljkUP5o=
 github.com/XSAM/otelsql v0.42.0/go.mod h1:4mOrEv+cS1KmKzrvTktvJnstr5GtKSAK+QHvFR9OcpI=
 github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo=
 github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=
+github.com/andybalholm/brotli v1.2.1 h1:R+f5xP285VArJDRgowrfb9DqL18yVK0gKAW/F+eTWro=
+github.com/andybalholm/brotli v1.2.1/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
 github.com/antithesishq/antithesis-sdk-go v0.5.0-default-no-op h1:Ucf+QxEKMbPogRO5guBNe5cgd9uZgfoJLOYs8WWhtjM=
 github.com/antithesishq/antithesis-sdk-go v0.5.0-default-no-op/go.mod h1:IUpT2DPAKh6i/YhSbt6Gl3v2yvUZjmKncl7U91fup7E=
 github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew1u1fNQOlOtuGxQY=
@@ -133,12 +135,6 @@ github.com/cenkalti/backoff/v5 v5.0.3 h1:ZN+IMa753KfX5hd8vVaMixjnqRZ3y8CuJKRKj1x
 github.com/cenkalti/backoff/v5 v5.0.3/go.mod h1:rkhZdG3JZukswDf7f0cwqPNk4K0sa+F97BxZthm/crw=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
-github.com/clipperhouse/displaywidth v0.6.2 h1:ZDpTkFfpHOKte4RG5O/BOyf3ysnvFswpyYrV7z2uAKo=
-github.com/clipperhouse/displaywidth v0.6.2/go.mod h1:R+kHuzaYWFkTm7xoMmK1lFydbci4X2CicfbGstSGg0o=
-github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
-github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
-github.com/clipperhouse/uax29/v2 v2.3.0 h1:SNdx9DVUqMoBuBoW3iLOj4FQv3dN5mDtuqwuhIGpJy4=
-github.com/clipperhouse/uax29/v2 v2.3.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
 github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
 github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
@@ -334,10 +330,10 @@ github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy
 github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
 github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
-github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
-github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp6Zk=
 github.com/mattn/go-sqlite3 v1.14.34/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/meilisearch/meilisearch-go v0.36.3 h1:Yx1aTY5jDgtbStPVkhJTDoLnZTy5sejQSPyjfNMy6e4=
+github.com/meilisearch/meilisearch-go v0.36.3/go.mod h1:hWcR0MuWLSzHfbz9GGzIr3s9rnXLm1jqkmHkJPbUSvM=
 github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY=
 github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg=
 github.com/minio/highwayhash v1.0.4-0.20251030100505-070ab1a87a76 h1:KGuD/pM2JpL9FAYvBrnBBeENKZNh6eNtjqytV6TYjnk=
@@ -358,14 +354,6 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/olahol/melody v1.4.0 h1:Pa5SdeZL/zXPi1tJuMAPDbl4n3gQOThSL6G1p4qZ4SI=
 github.com/olahol/melody v1.4.0/go.mod h1:GgkTl6Y7yWj/HtfD48Q5vLKPVoZOH+Qqgfa7CvJgJM4=
-github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6 h1:zrbMGy9YXpIeTnGj4EljqMiZsIcE09mmF8XsD5AYOJc=
-github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6/go.mod h1:rEKTHC9roVVicUIfZK7DYrdIoM0EOr8mK1Hj5s3JjH0=
-github.com/olekukonko/errors v1.1.0 h1:RNuGIh15QdDenh+hNvKrJkmxxjV4hcS50Db478Ou5sM=
-github.com/olekukonko/errors v1.1.0/go.mod h1:ppzxA5jBKcO1vIpCXQ9ZqgDh8iwODz6OXIGKU8r5m4Y=
-github.com/olekukonko/ll v0.1.4-0.20260115111900-9e59c2286df0 h1:jrYnow5+hy3WRDCBypUFvVKNSPPCdqgSXIE9eJDD8LM=
-github.com/olekukonko/ll v0.1.4-0.20260115111900-9e59c2286df0/go.mod h1:b52bVQRRPObe+yyBl0TxNfhesL0nedD4Cht0/zx55Ew=
-github.com/olekukonko/tablewriter v1.1.3 h1:VSHhghXxrP0JHl+0NnKid7WoEmd9/urKRJLysb70nnA=
-github.com/olekukonko/tablewriter v1.1.3/go.mod h1:9VU0knjhmMkXjnMKrZ3+L2JhhtsQ/L38BbL3CRNE8tM=
 github.com/onsi/ginkgo/v2 v2.9.2 h1:BA2GMJOtfGAfagzYtrAlufIP0lq6QERkFmHLMLPwFSU=
 github.com/onsi/ginkgo/v2 v2.9.2/go.mod h1:WHcJJG2dIlcCqVfBAwUCrJxSPFb6v4azBwgxeMeDuts=
 github.com/onsi/gomega v1.27.6 h1:ENqfyGeS5AX/rlXDd/ETokDz93u0YufY1Pgxuy/PvWE=
@@ -409,10 +397,6 @@ github.com/shirou/gopsutil/v4 v4.26.5 h1:RPcBXkpz7kOj9PqGFQOlBPZHsyaPvPVQc098y9R
 github.com/shirou/gopsutil/v4 v4.26.5/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1vwZ3Je0FKVCfqOLp5zO6trqMLYs0=
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
-github.com/spf13/cobra v1.7.0 h1:hyqWnYt1ZQShIddO5kBpj3vu05/++x6tJ6dg8EC572I=
-github.com/spf13/cobra v1.7.0/go.mod h1:uLxZILRyS/50WlhOIKD7W6V5bgeIt+4sICxh6uRMrb0=
-github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
-github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spiffe/go-spiffe/v2 v2.6.0 h1:l+DolpxNWYgruGQVV0xsfeya3CsC7m8iBzDnMpsbLuo=
 github.com/spiffe/go-spiffe/v2 v2.6.0/go.mod h1:gm2SeUoMZEtpnzPNs2Csc0D/gX33k1xIx7lEzqblHEs=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -441,6 +425,8 @@ github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYI
 github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
 github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
 github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
 github.com/yeqown/go-qrcode/v2 v2.2.5 h1:HCOe2bSjkhZyYoyyNaXNzh4DJZll6inVJQQw+8228Zk=
 github.com/yeqown/go-qrcode/v2 v2.2.5/go.mod h1:uHpt9CM0V1HeXLz+Wg5MN50/sI/fQhfkZlOM+cOTHxw=
 github.com/yeqown/go-qrcode/writer/standard v1.3.0 h1:chdyhEfRtUPgQtuPeaWVGQ/TQx4rE1PqeoW3U+53t34=

backend/internal/core/services/main_test.go

@@ -75,7 +75,7 @@ func MainNoExit(m *testing.M) int {
 		Enabled: false,
 		Width:   0,
 		Height:  0,
-	})
+	}, nil)
 
 	err = os.MkdirAll(os.TempDir()+"/homebox", 0o755)
 	if err != nil {

backend/internal/core/services/service_items_attachments_test.go

@@ -76,7 +76,7 @@ func TestEntityService_AddAttachment_InvalidStorage(t *testing.T) {
 		Enabled: false,
 		Width:   0,
 		Height:  0,
-	})
+	}, nil)
 
 	svc.repo = invalidRepos
 

backend/internal/data/repo/main_test.go

@@ -64,7 +64,7 @@ func MainNoExit(m *testing.M) int {
 		Enabled: false,
 		Width:   0,
 		Height:  0,
-	})
+	}, nil)
 	err = os.MkdirAll(os.TempDir()+"/homebox", 0o755)
 	if err != nil {
 		return 0