# ObjectBox Swift: an embedded database with vector search built in

> ObjectBox Swift is a NoSQL database for iOS and macOS that persists Swift objects directly, with on-device vector search, relations, queries across relations and automatic schema migrations. It is distributed as an xcframework through Swift Package Manager or CocoaPods, and its local vector search is what makes on-device Edge AI features practical without a server round trip.

**objectbox/objectbox-swift** — Swift database - fast, simple and lightweight (iOS, macOS)

- Repository: https://github.com/objectbox/objectbox-swift
- Website: https://swift.objectbox.io
- Stars: 620 · Forks: 37
- Language: Swift
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/objectbox-objectbox-swift

## What ObjectBox Swift is for

ObjectBox Swift is a NoSQL database that persists Swift objects on iOS and macOS. The pitch is that the objects you already model in Swift are the things you store, with a statically typed API that gives compile time checks and optimisations, and no mapping layer between your model and the store.

The positioning in the project documentation is deliberately about frugality rather than speed alone. It describes the database as simple yet capable, and frugal but fast, and argues that its resource use in CPU, memory and battery makes it a sustainable choice for iOS apps. The offline-first framing is the same idea from the product side: a local store that keeps working without a network, which is also what makes on-device AI features possible.

The features list groups several distinct things. On-device vector search is the headline, aimed at Edge AI features that run locally, privately and quickly. High performance on restricted devices is called out for IoT gateways, microcontrollers and ECUs. Relations are built in, so object links are a first class concept rather than a join table you write yourself. Queries can filter as needed, including across relations. Schema migrations are automatic, so no update scripts are needed.

Multiplatform support is listed as Linux, Windows, Android, iOS and macOS, and two commercial extensions sit alongside the local store: ObjectBox Sync, which keeps data in sync between devices and servers, and ObjectBox TS, a time series extension for time based data.

The users are mobile and desktop app developers who need local persistence and, increasingly, a local vector index.

## The entity model and the four operations that matter

The demo code in the documentation is short enough to read in one pass, and it shows the whole model.

```swift
// objectbox: entity
class Person {
    var id: Id = 0
    var firstName: String = ""
    var lastName: String = ""
    
    init() {}
    
    init(id: Id = 0, firstName: String, lastName: String) {
        self.id = id
        self.firstName = firstName
        self.lastName = lastName
    }
}

let store = try Store(directoryPath: "person-db")
let box = store.box(for: Person.self)

var person = Person(firstName: "Joe", lastName: "Green")
let id = try box.put(person) // Create

person = try box.get(id)!    // Read

person.lastName = "Black"
try box.put(person)          // Update

try box.remove(person.id)    // Delete

let query = try box.query {  // Query
    Person.firstName == "Joe"
    && Person.lastName.startsWith("B")
}.build()
let people: [Person] = try query.find()
```

The mechanism is a store, which owns the database on disk, and a box, which is the typed collection for one entity class. Putting an object returns its Id, getting takes an Id and returns the object back, and removing takes an Id. Queries are built with a closure that reads like a predicate, and a condition on one property can be combined with another.

The important detail is the single comment line at the top of the class. The objectbox: entity marker is what the code generator looks for, and it is why the API can be typed at all. The generator produces the binding code for that entity, which is also why the CocoaPods install has a separate setup step that adds a build phase to run the generator on every build.

## Adding the package through Swift Package Manager

ObjectBox is distributed as a Swift Package and as a CocoaPods pod, and the documentation covers both.

For an Xcode project, the instructions are to add a package dependency and search for a package URL, which is the objectbox-swift-spm repository:

```bash
https://github.com/objectbox/objectbox-swift-spm
```

The dependency rule to use is Up to Next Major Version, and the documentation says to view the tags of the objectbox-swift-spm repository to find the latest version to use. When Xcode asks, you add the ObjectBox.xcframework to your app target.

For a Swift Package Manager manifest, the package repository goes into the dependencies block, with the version you want pinned in the from argument, and the product goes into the target's dependencies:

```swift
.product(name: "ObjectBox.xcframework", package: "objectbox-swift-spm")
```

If you want ObjectBox Sync, which the documentation notes requires access to the Sync feature, you add ObjectBox-Sync.xcframework instead:

```swift
.product(name: "ObjectBox-Sync.xcframework", package: "objectbox-swift-spm")
```

The full manifest shape the documentation gives combines those pieces, with a dependencies array and a targets array where the executable target lists the xcframework product.

The version in the from argument has to be replaced with the latest tag of the objectbox-swift-spm repository. The Swift binding in this repository and the package that actually carries the binary are separate repositories, which is a detail worth knowing when you are pinning versions.

## The CocoaPods path and the code generator build phase

The CocoaPods route is the older one and it has an extra moving part.

You add a pod line to your Podfile:

```bash
pod 'ObjectBox'
```

Then you install the pod and run the ObjectBox setup script:

```bash
pod install --repo-update
Pods/ObjectBox/setup.rb
```

The setup script configures your Xcode project to run the ObjectBox generator on every build. It does this by adding a build phase, named Update Sourcery Generated Files, for every target with an executable. The generator is the piece that reads your entity classes and produces the typed binding code.

Two build settings have to be right for that to work. The documentation says to disable the User Script Sandboxing option in your Xcode project build settings so the generator script is allowed to run, and it notes that the code generator needs to run in the project directory and will generate files there.

That last point has consequences beyond the first build. A generator that writes into your source tree is a difference from a pure library dependency, and it interacts with build phase ordering, with clean builds, and with anyone who has to reproduce the project on another machine.

If you are choosing between the two distribution routes, the Swift Package Manager path is the one the project documents first, and the CocoaPods path is the one that needs a script to run after install.

## Where the vector search actually fits

The on-device vector search is the feature that separates this from a general embedded key value store, and it is worth being clear about what it changes.

Without it, a similarity search means an embedding service on a server. The device sends a vector, waits for a round trip, and the app depends on connectivity for the feature to work. With a local vector index, the lookup happens on the device, which removes the network dependency and keeps the data local, which is the privacy argument the project makes for on-device AI.

The rest of the feature set is what makes that usable rather than a demo. Vector search on its own would be a narrow addition, but it sits on a store that already has relations, so a vector result can be joined back to the object graph it came from. Relations being built in means you do not have to denormalise a document store into a flat key value map to get your model back.

There is a cost to the design worth naming. The data model is an object graph, not tables, and the query language is a Swift closure rather than SQL. That is pleasant when your domain is objects and awkward when your domain is records, and switching later means rewriting every query.

The commercial split is also visible here. The local store and the vector search are in the open source package, while ObjectBox Sync is a separate feature that needs access, and ObjectBox TS is a separate extension for time based data.

## Where ObjectBox Swift is the wrong choice

The first limit is the licensing picture. The repository here is under the Apache-2.0 licence with the text in LICENSE.txt, so the local store is permissively licensed. ObjectBox Sync, however, is described in the documentation as requiring access to the Sync feature, which is a commercial product. Anyone planning multi device replication needs to price that separately, and the readme treats it as a normal feature bullet rather than as a commercial decision point, so it is easy to miss.

The second is the code generator as a build requirement. On the CocoaPods path, a script has to run in your project directory on every build, and the User Script Sandboxing option has to be disabled for it. That is friction for teams with strict build hygiene, and it is friction for CI environments where the build phase has to be reproducible.

The third is the platform floor. The package is an xcframework, which is the Apple world, and the multiplatform claim covers the ObjectBox family rather than this binding specifically. A Swift server application on Linux is a different story from a Swift iOS app.

The fourth is the model fit. ObjectBox is a NoSQL object store with a Swift-native API. If your data is genuinely relational, with many to many relationships and reporting queries over them, then modelling that in an object graph and querying it with closures will be more work than a relational store, not less.

Compare that with the alternative of using SwiftData or Core Data, which ship with the platform and are the default answer for local persistence on iOS. The difference in approach is that those are Apple's own persistence, so there is no additional dependency and no generator to run, while ObjectBox adds an explicitly typed query layer, relations, and a local vector index, and takes on the dependency and the generator. If all you need is to store objects offline, the platform's own store is the lighter answer, and ObjectBox earns its place when the vector search or the query layer is the reason you are here.

## Licence, releases and the state of the repository

ObjectBox Swift is released under the Apache-2.0 licence, with the terms in the LICENSE.txt file at the repository root. The Apache 2.0 terms allow use and redistribution in closed and open source products, provided the copyright notice and licence text accompany copies, and they ask you to state notable modifications when redistributing. Read the file yourself for the exact wording, and read the Sync terms separately if replication is part of the plan, since that feature is licensed on its own.

The release history shows a steady 5.x line. v5.3.0 was tagged on 2026-05-19, preceded by v5.3.0-beta.4 on 2026-03-26 and v5.3.0-beta.3 on 2026-03-24. The repository is not archived, and the last push was on 2026-05-19, the same day as the current stable tag.

So the code is current, but the last push is more than five months before the current date. That is a gap worth factoring into your planning if you are picking a database for a long lived app, because the rate of change here has been slower than in the first months of a 5.x line. Check the CHANGELOG.md in the repository before you upgrade, and pin the version you validate against.

The tree is small and conventional. There is a Source/ directory with the Swift code, an Example/ directory with iOS and macOS sample apps and a shared folder, a Package.swift at the root, and a .gitmodules file, which points at the binary dependency being pulled in rather than vendored. The Example directory also contains model JSON files for the iOS and macOS variants, and the repository carries both a .github/ and a .gitlab/ directory, so the continuous integration runs on two platforms.

## Conclusion

ObjectBox Swift fits an iOS or macOS team that wants a local store with a Swift-native API, relations, and local vector search for on-device AI, and that would rather not run a separate vector service for a feature that only needs nearest neighbour lookup on the device. It does not fit a team that needs an open source store with no commercial dependency, because ObjectBox Sync is a separately licensed feature, or a team that wants a plain relational store with SQL. Before adopting it, check whether your data model fits the object graph model rather than tables, confirm the xcframework packaging works with your build and signing setup, and read the Sync terms separately if you plan to replicate between devices.

## FAQ

### How do I add ObjectBox Swift to an Xcode project?

Add a package dependency pointing at https://github.com/objectbox/objectbox-swift-spm, use the Up to Next Major Version dependency rule, and add the ObjectBox.xcframework to your app target when Xcode asks. Add ObjectBox-Sync.xcframework instead if you use ObjectBox Sync, which requires access to the Sync feature.

### How do I store and query a Swift object with ObjectBox?

Create a Store with a directory path, get a typed box with store.box(for: Person.self), then use put to create or update, get to read by Id, remove to delete, and a query closure such as Person.firstName == "Joe" to filter. The entity class needs the objectbox: entity marker so the generator can produce the binding.

### What is the ObjectBox code generator and when does it run?

The generator reads your entity classes and produces the typed binding code. With CocoaPods, the setup.rb script adds a build phase called Update Sourcery Generated Files to every target with an executable, so it runs on every build, and it writes the generated files into the project directory.

### Is ObjectBox Swift open source and what licence does it use?

The Swift binding is released under the Apache-2.0 licence, with the terms in the LICENSE.txt file at the repository root. ObjectBox Sync is a separate feature that requires access, so it carries its own terms rather than the repository's licence.

### What on-device AI features does ObjectBox Swift support?

The project documents fast local vector search for on-device AI, running locally, privately and quickly, so a nearest neighbour lookup does not need a server round trip. It also documents ObjectBox TS as a time series extension for time based data.

## Sources

- [License: Apache-2.0](https://github.com/objectbox/objectbox-swift/blob/main/LICENSE)
- [objectbox/objectbox-swift on GitHub](https://github.com/objectbox/objectbox-swift)
- [Project website](https://swift.objectbox.io)
- [README](https://github.com/objectbox/objectbox-swift/blob/main/README.md)
- [Releases](https://github.com/objectbox/objectbox-swift/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/objectbox-objectbox-swift