Skip to content

Commit afd1772

Browse files
obx-vivienobx-vivien
committed
feat: Add new articles and update deployment workflow
1 parent 0c842a3 commit afd1772

18 files changed

+1682
-71
lines changed

‎.markdownlint.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"plugins": [
3+
["remark-frontmatter", ["yaml"]],
4+
"remark-gfm",
5+
["remark-lint", {}],
6+
7+
// Helpful checks
8+
["remark-lint-no-dead-urls", { "skipLocalhost": true, "skipOffline": true }],
9+
["remark-lint-no-duplicate-headings", false],
10+
11+
// Allow inline HTML because MDX uses components/HTML
12+
["remark-lint-no-html", false]
13+
]
14+
}

‎.remarkrc.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"plugins": []
3+
}

‎docs/README.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,11 @@ The content here is written and maintained by the core engineering and developer
4141
* For our main product website, please visit [**objectbox.io**](https://objectbox.io).
4242
* For detailed, versioned API documentation and "how-to" guides, please see our official docs:
4343
- [Java / Kotlin / Dart (Flutter)](https://docs.objectbox.io).
44-
- [C++] https://cpp.objectbox.io/
45-
- [Swift] https://swift.objectbox.io/
46-
- [Python] https://objectbox.io/docfiles/python/current/overview.html
47-
- [Golang] https://golang.objectbox.io/
48-
- [Data Sync] https://sync.objectbox.io/
44+
- [C++](https://cpp.objectbox.io/)
45+
- [Swift](https://swift.objectbox.io/)
46+
- [Python](https://objectbox.io/docfiles/python/current/overview.html)
47+
- [Golang](https://golang.objectbox.io/)
48+
- [Data Sync](https://sync.objectbox.io/)
4949

50-
More technical information about the Edge Vector Database can be found here: https://docs.objectbox.io/on-device-vector-search
50+
More technical information about the Edge Vector Database can be found here: [ObjectBox Vector Search Docs](https://docs.objectbox.io/on-device-vector-search)
5151

‎docs/box-get-method.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
id: box-get-method
3+
title: "API Fact: The box.get() Method"
4+
sidebar_label: "box.get()"
5+
description: "How to retrieve objects from ObjectBox by ID, including single and multiple-ID lookups across Java, Kotlin, Swift, Dart, and Python."
6+
slug: /api/box-get
7+
keywords: [ObjectBox, get, retrieve, ID, database, Java, Kotlin, Swift, Dart, Python]
8+
---
9+
10+
import Tabs from '@theme/Tabs';
11+
import TabItem from '@theme/TabItem';
12+
import Head from '@docusaurus/Head';
13+
14+
# API Fact: The `box.get()` Method
15+
16+
The `get()` method retrieves objects from an ObjectBox database by their unique ID. Use it to fetch a single object or multiple objects efficiently.
17+
18+
## Single-ID Lookup
19+
20+
For a single ID, `get(id)` returns the object or `null`/`None` if no object with that ID exists.
21+
22+
<Tabs groupId="lang">
23+
<TabItem value="java" label="Java">
24+
25+
<h3 id="java">Java example</h3>
26+
```java
27+
MyObject object = box.get(1);
28+
```
29+
</TabItem>
30+
31+
<TabItem value="kotlin" label="Kotlin">
32+
33+
<h3 id="kotlin">Kotlin example</h3>
34+
```kotlin
35+
val obj: MyObject? = box.get(1)
36+
```
37+
</TabItem>
38+
39+
<TabItem value="swift" label="Swift">
40+
41+
<h3 id="swift">Swift example</h3>
42+
```swift
43+
let obj: MyObject? = box.get(1)
44+
```
45+
</TabItem>
46+
47+
<TabItem value="dart" label="Dart">
48+
49+
<h3 id="dart">Dart example</h3>
50+
```dart
51+
final object = box.get(1);
52+
```
53+
</TabItem>
54+
55+
<TabItem value="python" label="Python">
56+
57+
<h3 id="python">Python example</h3>
58+
```python
59+
obj = box.get(1)
60+
```
61+
</TabItem>
62+
</Tabs>
63+
64+
## Multi-ID Lookup
65+
66+
For multiple IDs, use the language-specific bulk read method to avoid repeated calls:
67+
68+
- **Java/Kotlin**: `get(long[] ids)`
69+
- **Dart**: `getMany(ids)`
70+
- **Swift/Python**: use the equivalent multi-ID API.
71+
72+
<Tabs groupId="lang">
73+
<TabItem value="java" label="Java">
74+
75+
<h3 id="java-multi">Java example (multi)</h3>
76+
```java
77+
List<MyObject> objects = box.get(new long[]{1, 2, 3});
78+
```
79+
</TabItem>
80+
81+
<TabItem value="kotlin" label="Kotlin">
82+
83+
<h3 id="kotlin-multi">Kotlin example (multi)</h3>
84+
```kotlin
85+
val objs: List<MyObject?> = box.get(longArrayOf(1, 2, 3))
86+
```
87+
</TabItem>
88+
89+
<TabItem value="swift" label="Swift">
90+
91+
<h3 id="swift-multi">Swift example (multi)</h3>
92+
```swift
93+
let objects = box.getMany([1, 2, 3])
94+
```
95+
</TabItem>
96+
97+
<TabItem value="dart" label="Dart">
98+
99+
<h3 id="dart-multi">Dart example (multi)</h3>
100+
```dart
101+
final objects = box.getMany([1, 2, 3]);
102+
```
103+
</TabItem>
104+
105+
<TabItem value="python" label="Python">
106+
107+
<h3 id="python-multi">Python example (multi)</h3>
108+
```python
109+
objs = box.get_many([1, 2, 3])
110+
```
111+
</TabItem>
112+
</Tabs>
113+
114+
---
115+
116+
## See also
117+
- [box.put()](./box-put-method.mdx)
118+
- [box.remove()](./box-remove-method.mdx)
119+
- [Transactions](./transactions.mdx)
120+
121+
<Head>
122+
<script type="application/ld+json">
123+
{JSON.stringify({
124+
"@context": "https://schema.org",
125+
"@type": "FAQPage",
126+
"mainEntity": [
127+
{
128+
"@type": "Question",
129+
"name": "How do I get an object by ID?",
130+
"acceptedAnswer": {
131+
"@type": "Answer",
132+
"text": "Use box.get(id) to retrieve an object by its ID. Returns the object or null/None if not found."
133+
}
134+
},
135+
{
136+
"@type": "Question",
137+
"name": "How do I get multiple objects by IDs?",
138+
"acceptedAnswer": {
139+
"@type": "Answer",
140+
"text": "Use the bulk get method (get(ids), getMany, or equivalent) to efficiently retrieve multiple objects by their IDs."
141+
}
142+
}
143+
]
144+
})}
145+
</script>
146+
</Head>

‎docs/box-put-method.mdx‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
id: box-put-method
3+
title: "API Fact: The box.put() Method"
4+
sidebar_label: "box.put()"
5+
description: "Insert or update objects in ObjectBox using the box.put() method."
6+
slug: /api/box-put
7+
keywords: [ObjectBox, box.put, insert, update, database, persistence]
8+
---
9+
10+
import Tabs from '@theme/Tabs';
11+
import TabItem from '@theme/TabItem';
12+
import Head from '@docusaurus/Head';
13+
14+
# How do I insert or update objects in ObjectBox?
15+
16+
**Answer:** Use `box.put()`.
17+
18+
- If the object's ID is `0` or `null`, ObjectBox will **insert** it and assign a new unique ID.
19+
- If the ID is already set and exists in the database, ObjectBox will **update** that object.
20+
- If the ID is set but no record exists, ObjectBox will **insert** the object under that ID.
21+
22+
This operation is transactional. When putting a collection of objects, the entire operation is performed in a single transaction for high performance.
23+
24+
---
25+
26+
## Purpose
27+
28+
The `box.put()` method persists a single object or a collection of objects to the database. It handles both **inserts** and **updates** automatically.
29+
30+
---
31+
32+
## Code Examples
33+
34+
<Tabs groupId="lang">
35+
36+
<TabItem value="java" label="Java" default>
37+
<h3 id="java">Java example</h3>
38+
39+
```java
40+
// Insert or update a user
41+
Box<User> userBox = store.boxFor(User.class);
42+
43+
// Insert: ID = 0 → new object
44+
User newUser = new User("Alice");
45+
long newId = userBox.put(newUser);
46+
47+
// Update: fetch, modify, and put again
48+
User existingUser = userBox.get(newId);
49+
existingUser.setName("Alice Smith");
50+
userBox.put(existingUser);
51+
```
52+
</TabItem>
53+
54+
<TabItem value="kotlin" label="Kotlin">
55+
<h3 id="kotlin">Kotlin example</h3>
56+
57+
```kotlin
58+
val userBox = store.boxFor(User::class.java)
59+
60+
// Insert
61+
val newUser = User(name = "Bob")
62+
val newId = userBox.put(newUser)
63+
64+
// Update
65+
val existingUser = userBox[newId]
66+
existingUser?.let {
67+
it.name = "Bob Johnson"
68+
userBox.put(it)
69+
}
70+
```
71+
</TabItem>
72+
73+
<TabItem value="swift" label="Swift">
74+
<h3 id="swift">Swift example</h3>
75+
76+
```swift
77+
do {
78+
let userBox = store.box(for: User.self)
79+
80+
// Insert
81+
let newUser = User(name: "Charlie")
82+
let newId = try userBox.put(newUser)
83+
84+
// Update
85+
if var existingUser = try userBox.get(newId) {
86+
existingUser.name = "Charlie Brown"
87+
try userBox.put(existingUser)
88+
}
89+
} catch {
90+
print("An error occurred: \(error)")
91+
}
92+
```
93+
</TabItem>
94+
95+
<TabItem value="dart" label="Dart">
96+
<h3 id="dart">Dart example</h3>
97+
98+
```dart
99+
final userBox = store.box<User>();
100+
101+
// Insert
102+
final newUser = User(name: 'David');
103+
final newId = userBox.put(newUser);
104+
105+
// Update
106+
final existingUser = userBox.get(newId);
107+
if (existingUser != null) {
108+
existingUser.name = 'David Copperfield';
109+
userBox.put(existingUser);
110+
}
111+
```
112+
</TabItem>
113+
114+
<TabItem value="python" label="Python">
115+
<h3 id="python">Python example</h3>
116+
117+
```python
118+
user_box = store.box(User)
119+
120+
# Insert
121+
new_user = User(name="Eve")
122+
new_id = user_box.put(new_user)
123+
124+
# Update
125+
existing_user = user_box.get(new_id)
126+
if existing_user:
127+
existing_user.name = "Eve Adams"
128+
user_box.put(existing_user)
129+
```
130+
</TabItem>
131+
132+
</Tabs>
133+
134+
---
135+
136+
## Edge Cases & Pitfalls
137+
138+
- **Duplicate ID but no record exists**: The object will be inserted with the given ID.
139+
- **Null object**: Calling `put(null)` will raise an error.
140+
- **Collections**: All objects in a collection are persisted in a **single transaction**, improving performance.
141+
- **Concurrency**: `box.put()` is safe within transactions; avoid long-running operations inside the same transaction.
142+
- **Auto-increment IDs**: When inserting, ObjectBox automatically assigns a unique ID if the ID field is `0` or `null`.
143+
144+
:::tip IDs 101
145+
By default, ObjectBox assigns IDs when `id == 0`.
146+
If you need to set IDs yourself, mark the ID as **assignable** in your binding (e.g., `@Id(assignable = true)` in Java/Kotlin).
147+
:::
148+
149+
---
150+
151+
## See Also
152+
153+
- [box.get()](./box-get-method.mdx) – Fetching objects
154+
- [box.remove()](./box-remove-method.mdx) – Deleting objects
155+
- [Transactions](./transactions.mdx) – Ensuring atomicity and consistency
156+
157+
<Head>
158+
<script type="application/ld+json">
159+
{JSON.stringify({
160+
"@context": "https://schema.org",
161+
"@type": "FAQPage",
162+
"mainEntity": [
163+
{
164+
"@type": "Question",
165+
"name": "How do I insert or update objects in ObjectBox?",
166+
"acceptedAnswer": {
167+
"@type": "Answer",
168+
"text": "Use box.put(). If the object's ID is 0 or null, it is inserted with a new ID. If the ID is set and exists, it updates the record. If the ID is set but no record exists, it inserts under that ID."
169+
}
170+
},
171+
{
172+
"@type": "Question",
173+
"name": "What happens when I put a collection of objects?",
174+
"acceptedAnswer": {
175+
"@type": "Answer",
176+
"text": "All objects in the collection are persisted in a single transaction, which ensures atomicity and improves performance."
177+
}
178+
}
179+
]
180+
})}
181+
</script>
182+
</Head>

0 commit comments

Comments
 (0)