A loose federation of distributed, typed datasets
1<!DOCTYPE html>
2<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
3
4<meta charset="utf-8">
5<meta name="generator" content="quarto-1.7.34">
6
7<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
8
9<meta name="description" content="Common issues and frequently asked questions">
10
11<title>Troubleshooting & FAQ – atdata</title>
12<style>
13code{white-space: pre-wrap;}
14span.smallcaps{font-variant: small-caps;}
15div.columns{display: flex; gap: min(4vw, 1.5em);}
16div.column{flex: auto; overflow-x: auto;}
17div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
18ul.task-list{list-style: none;}
19ul.task-list li input[type="checkbox"] {
20 width: 0.8em;
21 margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */
22 vertical-align: middle;
23}
24/* CSS for syntax highlighting */
25html { -webkit-text-size-adjust: 100%; }
26pre > code.sourceCode { white-space: pre; position: relative; }
27pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
28pre > code.sourceCode > span:empty { height: 1.2em; }
29.sourceCode { overflow: visible; }
30code.sourceCode > span { color: inherit; text-decoration: inherit; }
31div.sourceCode { margin: 1em 0; }
32pre.sourceCode { margin: 0; }
33@media screen {
34div.sourceCode { overflow: auto; }
35}
36@media print {
37pre > code.sourceCode { white-space: pre-wrap; }
38pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
39}
40pre.numberSource code
41 { counter-reset: source-line 0; }
42pre.numberSource code > span
43 { position: relative; left: -4em; counter-increment: source-line; }
44pre.numberSource code > span > a:first-child::before
45 { content: counter(source-line);
46 position: relative; left: -1em; text-align: right; vertical-align: baseline;
47 border: none; display: inline-block;
48 -webkit-touch-callout: none; -webkit-user-select: none;
49 -khtml-user-select: none; -moz-user-select: none;
50 -ms-user-select: none; user-select: none;
51 padding: 0 4px; width: 4em;
52 }
53pre.numberSource { margin-left: 3em; padding-left: 4px; }
54div.sourceCode
55 { }
56@media screen {
57pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
58}
59</style>
60
61
62<script src="../site_libs/quarto-nav/quarto-nav.js"></script>
63<script src="../site_libs/quarto-nav/headroom.min.js"></script>
64<script src="../site_libs/clipboard/clipboard.min.js"></script>
65<script src="../site_libs/quarto-search/autocomplete.umd.js"></script>
66<script src="../site_libs/quarto-search/fuse.min.js"></script>
67<script src="../site_libs/quarto-search/quarto-search.js"></script>
68<meta name="quarto:offset" content="../">
69<script src="../site_libs/quarto-html/quarto.js" type="module"></script>
70<script src="../site_libs/quarto-html/tabsets/tabsets.js" type="module"></script>
71<script src="../site_libs/quarto-html/popper.min.js"></script>
72<script src="../site_libs/quarto-html/tippy.umd.min.js"></script>
73<script src="../site_libs/quarto-html/anchor.min.js"></script>
74<link href="../site_libs/quarto-html/tippy.css" rel="stylesheet">
75<link href="../site_libs/quarto-html/quarto-syntax-highlighting-9582434199d49cc9e91654cdeeb4866b.css" rel="stylesheet" class="quarto-color-scheme" id="quarto-text-highlighting-styles">
76<link href="../site_libs/quarto-html/quarto-syntax-highlighting-dark-8dcd8563ea6803ab7cbb3d71ca5772e1.css" rel="stylesheet" class="quarto-color-scheme quarto-color-alternate" id="quarto-text-highlighting-styles">
77<link href="../site_libs/quarto-html/quarto-syntax-highlighting-9582434199d49cc9e91654cdeeb4866b.css" rel="stylesheet" class="quarto-color-scheme-extra" id="quarto-text-highlighting-styles">
78<script src="../site_libs/bootstrap/bootstrap.min.js"></script>
79<link href="../site_libs/bootstrap/bootstrap-icons.css" rel="stylesheet">
80<link href="../site_libs/bootstrap/bootstrap-62bce24ca844314e7bb1a34dbdfe05cc.min.css" rel="stylesheet" append-hash="true" class="quarto-color-scheme" id="quarto-bootstrap" data-mode="light">
81<link href="../site_libs/bootstrap/bootstrap-dark-7964ffd8887b0991fe8d71c6c8bc75d6.min.css" rel="stylesheet" append-hash="true" class="quarto-color-scheme quarto-color-alternate" id="quarto-bootstrap" data-mode="dark">
82<link href="../site_libs/bootstrap/bootstrap-62bce24ca844314e7bb1a34dbdfe05cc.min.css" rel="stylesheet" append-hash="true" class="quarto-color-scheme-extra" id="quarto-bootstrap" data-mode="light">
83<script id="quarto-search-options" type="application/json">{
84 "location": "navbar",
85 "copy-button": false,
86 "collapse-after": 3,
87 "panel-placement": "end",
88 "type": "overlay",
89 "limit": 50,
90 "keyboard-shortcut": [
91 "f",
92 "/",
93 "s"
94 ],
95 "show-item-context": false,
96 "language": {
97 "search-no-results-text": "No results",
98 "search-matching-documents-text": "matching documents",
99 "search-copy-link-title": "Copy link to search",
100 "search-hide-matches-text": "Hide additional matches",
101 "search-more-match-text": "more match in this document",
102 "search-more-matches-text": "more matches in this document",
103 "search-clear-button-title": "Clear",
104 "search-text-placeholder": "",
105 "search-detached-cancel-button-title": "Cancel",
106 "search-submit-button-title": "Submit",
107 "search-label": "Search"
108 }
109}</script>
110
111
112<link rel="stylesheet" href="../assets/styles.css">
113</head>
114
115<body class="nav-sidebar docked nav-fixed quarto-light"><script id="quarto-html-before-body" type="application/javascript">
116 const toggleBodyColorMode = (bsSheetEl) => {
117 const mode = bsSheetEl.getAttribute("data-mode");
118 const bodyEl = window.document.querySelector("body");
119 if (mode === "dark") {
120 bodyEl.classList.add("quarto-dark");
121 bodyEl.classList.remove("quarto-light");
122 } else {
123 bodyEl.classList.add("quarto-light");
124 bodyEl.classList.remove("quarto-dark");
125 }
126 }
127 const toggleBodyColorPrimary = () => {
128 const bsSheetEl = window.document.querySelector("link#quarto-bootstrap:not([rel=disabled-stylesheet])");
129 if (bsSheetEl) {
130 toggleBodyColorMode(bsSheetEl);
131 }
132 }
133 const setColorSchemeToggle = (alternate) => {
134 const toggles = window.document.querySelectorAll('.quarto-color-scheme-toggle');
135 for (let i=0; i < toggles.length; i++) {
136 const toggle = toggles[i];
137 if (toggle) {
138 if (alternate) {
139 toggle.classList.add("alternate");
140 } else {
141 toggle.classList.remove("alternate");
142 }
143 }
144 }
145 };
146 const toggleColorMode = (alternate) => {
147 // Switch the stylesheets
148 const primaryStylesheets = window.document.querySelectorAll('link.quarto-color-scheme:not(.quarto-color-alternate)');
149 const alternateStylesheets = window.document.querySelectorAll('link.quarto-color-scheme.quarto-color-alternate');
150 manageTransitions('#quarto-margin-sidebar .nav-link', false);
151 if (alternate) {
152 // note: dark is layered on light, we don't disable primary!
153 enableStylesheet(alternateStylesheets);
154 for (const sheetNode of alternateStylesheets) {
155 if (sheetNode.id === "quarto-bootstrap") {
156 toggleBodyColorMode(sheetNode);
157 }
158 }
159 } else {
160 disableStylesheet(alternateStylesheets);
161 enableStylesheet(primaryStylesheets)
162 toggleBodyColorPrimary();
163 }
164 manageTransitions('#quarto-margin-sidebar .nav-link', true);
165 // Switch the toggles
166 setColorSchemeToggle(alternate)
167 // Hack to workaround the fact that safari doesn't
168 // properly recolor the scrollbar when toggling (#1455)
169 if (navigator.userAgent.indexOf('Safari') > 0 && navigator.userAgent.indexOf('Chrome') == -1) {
170 manageTransitions("body", false);
171 window.scrollTo(0, 1);
172 setTimeout(() => {
173 window.scrollTo(0, 0);
174 manageTransitions("body", true);
175 }, 40);
176 }
177 }
178 const disableStylesheet = (stylesheets) => {
179 for (let i=0; i < stylesheets.length; i++) {
180 const stylesheet = stylesheets[i];
181 stylesheet.rel = 'disabled-stylesheet';
182 }
183 }
184 const enableStylesheet = (stylesheets) => {
185 for (let i=0; i < stylesheets.length; i++) {
186 const stylesheet = stylesheets[i];
187 if(stylesheet.rel !== 'stylesheet') { // for Chrome, which will still FOUC without this check
188 stylesheet.rel = 'stylesheet';
189 }
190 }
191 }
192 const manageTransitions = (selector, allowTransitions) => {
193 const els = window.document.querySelectorAll(selector);
194 for (let i=0; i < els.length; i++) {
195 const el = els[i];
196 if (allowTransitions) {
197 el.classList.remove('notransition');
198 } else {
199 el.classList.add('notransition');
200 }
201 }
202 }
203 const isFileUrl = () => {
204 return window.location.protocol === 'file:';
205 }
206 const hasAlternateSentinel = () => {
207 let styleSentinel = getColorSchemeSentinel();
208 if (styleSentinel !== null) {
209 return styleSentinel === "alternate";
210 } else {
211 return false;
212 }
213 }
214 const setStyleSentinel = (alternate) => {
215 const value = alternate ? "alternate" : "default";
216 if (!isFileUrl()) {
217 window.localStorage.setItem("quarto-color-scheme", value);
218 } else {
219 localAlternateSentinel = value;
220 }
221 }
222 const getColorSchemeSentinel = () => {
223 if (!isFileUrl()) {
224 const storageValue = window.localStorage.getItem("quarto-color-scheme");
225 return storageValue != null ? storageValue : localAlternateSentinel;
226 } else {
227 return localAlternateSentinel;
228 }
229 }
230 const toggleGiscusIfUsed = (isAlternate, darkModeDefault) => {
231 const baseTheme = document.querySelector('#giscus-base-theme')?.value ?? 'light';
232 const alternateTheme = document.querySelector('#giscus-alt-theme')?.value ?? 'dark';
233 let newTheme = '';
234 if(authorPrefersDark) {
235 newTheme = isAlternate ? baseTheme : alternateTheme;
236 } else {
237 newTheme = isAlternate ? alternateTheme : baseTheme;
238 }
239 const changeGiscusTheme = () => {
240 // From: https://github.com/giscus/giscus/issues/336
241 const sendMessage = (message) => {
242 const iframe = document.querySelector('iframe.giscus-frame');
243 if (!iframe) return;
244 iframe.contentWindow.postMessage({ giscus: message }, 'https://giscus.app');
245 }
246 sendMessage({
247 setConfig: {
248 theme: newTheme
249 }
250 });
251 }
252 const isGiscussLoaded = window.document.querySelector('iframe.giscus-frame') !== null;
253 if (isGiscussLoaded) {
254 changeGiscusTheme();
255 }
256 };
257 const authorPrefersDark = false;
258 const darkModeDefault = authorPrefersDark;
259 document.querySelector('link#quarto-text-highlighting-styles.quarto-color-scheme-extra').rel = 'disabled-stylesheet';
260 document.querySelector('link#quarto-bootstrap.quarto-color-scheme-extra').rel = 'disabled-stylesheet';
261 let localAlternateSentinel = darkModeDefault ? 'alternate' : 'default';
262 // Dark / light mode switch
263 window.quartoToggleColorScheme = () => {
264 // Read the current dark / light value
265 let toAlternate = !hasAlternateSentinel();
266 toggleColorMode(toAlternate);
267 setStyleSentinel(toAlternate);
268 toggleGiscusIfUsed(toAlternate, darkModeDefault);
269 window.dispatchEvent(new Event('resize'));
270 };
271 // Switch to dark mode if need be
272 if (hasAlternateSentinel()) {
273 toggleColorMode(true);
274 } else {
275 toggleColorMode(false);
276 }
277 </script>
278
279<div id="quarto-search-results"></div>
280 <header id="quarto-header" class="headroom fixed-top">
281 <nav class="navbar navbar-expand-lg " data-bs-theme="dark">
282 <div class="navbar-container container-fluid">
283 <div class="navbar-brand-container mx-auto">
284 <a class="navbar-brand" href="../index.html">
285 <span class="navbar-title">atdata</span>
286 </a>
287 </div>
288 <div id="quarto-search" class="" title="Search"></div>
289 <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" role="menu" aria-expanded="false" aria-label="Toggle navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
290 <span class="navbar-toggler-icon"></span>
291</button>
292 <div class="collapse navbar-collapse" id="navbarCollapse">
293 <ul class="navbar-nav navbar-nav-scroll me-auto">
294 <li class="nav-item">
295 <a class="nav-link active" href="../index.html" aria-current="page">
296<span class="menu-text">Guide</span></a>
297 </li>
298 <li class="nav-item dropdown ">
299 <a class="nav-link dropdown-toggle" href="#" id="nav-menu-tutorials" role="link" data-bs-toggle="dropdown" aria-expanded="false">
300 <span class="menu-text">Tutorials</span>
301 </a>
302 <ul class="dropdown-menu" aria-labelledby="nav-menu-tutorials">
303 <li>
304 <a class="dropdown-item" href="../tutorials/quickstart.html">
305 <span class="dropdown-text">Quick Start</span></a>
306 </li>
307 <li>
308 <a class="dropdown-item" href="../tutorials/local-workflow.html">
309 <span class="dropdown-text">Local Workflow</span></a>
310 </li>
311 <li>
312 <a class="dropdown-item" href="../tutorials/atmosphere.html">
313 <span class="dropdown-text">Atmosphere Publishing</span></a>
314 </li>
315 <li>
316 <a class="dropdown-item" href="../tutorials/promotion.html">
317 <span class="dropdown-text">Promotion Workflow</span></a>
318 </li>
319 </ul>
320 </li>
321 <li class="nav-item dropdown ">
322 <a class="nav-link dropdown-toggle" href="#" id="nav-menu-reference" role="link" data-bs-toggle="dropdown" aria-expanded="false">
323 <span class="menu-text">Reference</span>
324 </a>
325 <ul class="dropdown-menu" aria-labelledby="nav-menu-reference">
326 <li>
327 <a class="dropdown-item" href="../reference/architecture.html">
328 <span class="dropdown-text">Architecture Overview</span></a>
329 </li>
330 <li>
331 <a class="dropdown-item" href="../reference/packable-samples.html">
332 <span class="dropdown-text">Packable Samples</span></a>
333 </li>
334 <li>
335 <a class="dropdown-item" href="../reference/datasets.html">
336 <span class="dropdown-text">Datasets</span></a>
337 </li>
338 <li>
339 <a class="dropdown-item" href="../reference/lenses.html">
340 <span class="dropdown-text">Lenses</span></a>
341 </li>
342 <li>
343 <a class="dropdown-item" href="../reference/local-storage.html">
344 <span class="dropdown-text">Local Storage</span></a>
345 </li>
346 <li>
347 <a class="dropdown-item" href="../reference/atmosphere.html">
348 <span class="dropdown-text">Atmosphere</span></a>
349 </li>
350 <li>
351 <a class="dropdown-item" href="../reference/promotion.html">
352 <span class="dropdown-text">Promotion</span></a>
353 </li>
354 <li>
355 <a class="dropdown-item" href="../reference/load-dataset.html">
356 <span class="dropdown-text">load_dataset API</span></a>
357 </li>
358 <li>
359 <a class="dropdown-item" href="../reference/protocols.html">
360 <span class="dropdown-text">Protocols</span></a>
361 </li>
362 <li>
363 <a class="dropdown-item" href="../reference/uri-spec.html">
364 <span class="dropdown-text">URI Specification</span></a>
365 </li>
366 <li>
367 <a class="dropdown-item" href="../reference/troubleshooting.html">
368 <span class="dropdown-text">Troubleshooting & FAQ</span></a>
369 </li>
370 <li>
371 <a class="dropdown-item" href="../reference/deployment.html">
372 <span class="dropdown-text">Deployment Guide</span></a>
373 </li>
374 </ul>
375 </li>
376 <li class="nav-item">
377 <a class="nav-link" href="../api/index.html">
378<span class="menu-text">API</span></a>
379 </li>
380</ul>
381 <ul class="navbar-nav navbar-nav-scroll ms-auto">
382 <li class="nav-item compact">
383 <a class="nav-link" href="https://github.com/your-org/atdata"> <i class="bi bi-github" role="img">
384</i>
385<span class="menu-text"></span></a>
386 </li>
387</ul>
388 </div> <!-- /navcollapse -->
389 <div class="quarto-navbar-tools">
390 <a href="" class="quarto-color-scheme-toggle quarto-navigation-tool px-1" onclick="window.quartoToggleColorScheme(); return false;" title="Toggle dark mode"><i class="bi"></i></a>
391</div>
392 </div> <!-- /container-fluid -->
393 </nav>
394 <nav class="quarto-secondary-nav">
395 <div class="container-fluid d-flex">
396 <button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
397 <i class="bi bi-layout-text-sidebar-reverse"></i>
398 </button>
399 <nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../reference/architecture.html">Reference</a></li><li class="breadcrumb-item"><a href="../reference/troubleshooting.html">Troubleshooting & FAQ</a></li></ol></nav>
400 <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Toggle sidebar navigation" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
401 </a>
402 </div>
403 </nav>
404</header>
405<!-- content -->
406<div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-article page-navbar">
407<!-- sidebar -->
408 <nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation docked overflow-auto">
409 <div class="sidebar-menu-container">
410 <ul class="list-unstyled mt-1">
411 <li class="sidebar-item">
412 <div class="sidebar-item-container">
413 <a href="../index.html" class="sidebar-item-text sidebar-link">
414 <span class="menu-text">atdata</span></a>
415 </div>
416</li>
417 <li class="sidebar-item sidebar-item-section">
418 <div class="sidebar-item-container">
419 <a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="true">
420 <span class="menu-text">Getting Started</span></a>
421 <a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="true" aria-label="Toggle section">
422 <i class="bi bi-chevron-right ms-2"></i>
423 </a>
424 </div>
425 <ul id="quarto-sidebar-section-1" class="collapse list-unstyled sidebar-section depth1 show">
426 <li class="sidebar-item">
427 <div class="sidebar-item-container">
428 <a href="../tutorials/quickstart.html" class="sidebar-item-text sidebar-link">
429 <span class="menu-text">Quick Start</span></a>
430 </div>
431</li>
432 <li class="sidebar-item">
433 <div class="sidebar-item-container">
434 <a href="../tutorials/local-workflow.html" class="sidebar-item-text sidebar-link">
435 <span class="menu-text">Local Workflow</span></a>
436 </div>
437</li>
438 <li class="sidebar-item">
439 <div class="sidebar-item-container">
440 <a href="../tutorials/atmosphere.html" class="sidebar-item-text sidebar-link">
441 <span class="menu-text">Atmosphere Publishing</span></a>
442 </div>
443</li>
444 <li class="sidebar-item">
445 <div class="sidebar-item-container">
446 <a href="../tutorials/promotion.html" class="sidebar-item-text sidebar-link">
447 <span class="menu-text">Promotion Workflow</span></a>
448 </div>
449</li>
450 </ul>
451 </li>
452 <li class="sidebar-item sidebar-item-section">
453 <div class="sidebar-item-container">
454 <a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true">
455 <span class="menu-text">Reference</span></a>
456 <a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true" aria-label="Toggle section">
457 <i class="bi bi-chevron-right ms-2"></i>
458 </a>
459 </div>
460 <ul id="quarto-sidebar-section-2" class="collapse list-unstyled sidebar-section depth1 show">
461 <li class="sidebar-item">
462 <div class="sidebar-item-container">
463 <a href="../reference/architecture.html" class="sidebar-item-text sidebar-link">
464 <span class="menu-text">Architecture Overview</span></a>
465 </div>
466</li>
467 <li class="sidebar-item">
468 <div class="sidebar-item-container">
469 <a href="../reference/packable-samples.html" class="sidebar-item-text sidebar-link">
470 <span class="menu-text">Packable Samples</span></a>
471 </div>
472</li>
473 <li class="sidebar-item">
474 <div class="sidebar-item-container">
475 <a href="../reference/datasets.html" class="sidebar-item-text sidebar-link">
476 <span class="menu-text">Datasets</span></a>
477 </div>
478</li>
479 <li class="sidebar-item">
480 <div class="sidebar-item-container">
481 <a href="../reference/lenses.html" class="sidebar-item-text sidebar-link">
482 <span class="menu-text">Lenses</span></a>
483 </div>
484</li>
485 <li class="sidebar-item">
486 <div class="sidebar-item-container">
487 <a href="../reference/local-storage.html" class="sidebar-item-text sidebar-link">
488 <span class="menu-text">Local Storage</span></a>
489 </div>
490</li>
491 <li class="sidebar-item">
492 <div class="sidebar-item-container">
493 <a href="../reference/atmosphere.html" class="sidebar-item-text sidebar-link">
494 <span class="menu-text">Atmosphere (ATProto Integration)</span></a>
495 </div>
496</li>
497 <li class="sidebar-item">
498 <div class="sidebar-item-container">
499 <a href="../reference/promotion.html" class="sidebar-item-text sidebar-link">
500 <span class="menu-text">Promotion Workflow</span></a>
501 </div>
502</li>
503 <li class="sidebar-item">
504 <div class="sidebar-item-container">
505 <a href="../reference/load-dataset.html" class="sidebar-item-text sidebar-link">
506 <span class="menu-text">load_dataset API</span></a>
507 </div>
508</li>
509 <li class="sidebar-item">
510 <div class="sidebar-item-container">
511 <a href="../reference/protocols.html" class="sidebar-item-text sidebar-link">
512 <span class="menu-text">Protocols</span></a>
513 </div>
514</li>
515 <li class="sidebar-item">
516 <div class="sidebar-item-container">
517 <a href="../reference/uri-spec.html" class="sidebar-item-text sidebar-link">
518 <span class="menu-text">URI Specification</span></a>
519 </div>
520</li>
521 <li class="sidebar-item">
522 <div class="sidebar-item-container">
523 <a href="../reference/troubleshooting.html" class="sidebar-item-text sidebar-link active">
524 <span class="menu-text">Troubleshooting & FAQ</span></a>
525 </div>
526</li>
527 <li class="sidebar-item">
528 <div class="sidebar-item-container">
529 <a href="../reference/deployment.html" class="sidebar-item-text sidebar-link">
530 <span class="menu-text">Deployment Guide</span></a>
531 </div>
532</li>
533 </ul>
534 </li>
535 </ul>
536 </div>
537</nav>
538<div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"></div>
539<!-- margin-sidebar -->
540 <div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
541 <nav id="TOC" role="doc-toc" class="toc-active">
542 <h2 id="toc-title">On this page</h2>
543
544 <ul>
545 <li><a href="#common-errors" id="toc-common-errors" class="nav-link active" data-scroll-target="#common-errors">Common Errors</a>
546 <ul class="collapse">
547 <li><a href="#typeerror-type-object-is-not-subscriptable" id="toc-typeerror-type-object-is-not-subscriptable" class="nav-link" data-scroll-target="#typeerror-type-object-is-not-subscriptable">TypeError: ‘type’ object is not subscriptable</a></li>
548 <li><a href="#attributeerror-nonetype-object-has-no-attribute" id="toc-attributeerror-nonetype-object-has-no-attribute" class="nav-link" data-scroll-target="#attributeerror-nonetype-object-has-no-attribute">AttributeError: ‘NoneType’ object has no attribute…</a></li>
549 <li><a href="#runtimeerror-msgpack-field-not-found-in-sample" id="toc-runtimeerror-msgpack-field-not-found-in-sample" class="nav-link" data-scroll-target="#runtimeerror-msgpack-field-not-found-in-sample">RuntimeError: msgpack field not found in sample</a></li>
550 <li><a href="#valueerror-field-type-not-supported" id="toc-valueerror-field-type-not-supported" class="nav-link" data-scroll-target="#valueerror-field-type-not-supported">ValueError: Field type not supported</a></li>
551 <li><a href="#keyerror-when-iterating-dataset" id="toc-keyerror-when-iterating-dataset" class="nav-link" data-scroll-target="#keyerror-when-iterating-dataset">KeyError when iterating dataset</a></li>
552 </ul></li>
553 <li><a href="#faq" id="toc-faq" class="nav-link" data-scroll-target="#faq">FAQ</a>
554 <ul class="collapse">
555 <li><a href="#how-do-i-check-the-sample-type-of-a-dataset" id="toc-how-do-i-check-the-sample-type-of-a-dataset" class="nav-link" data-scroll-target="#how-do-i-check-the-sample-type-of-a-dataset">How do I check the sample type of a dataset?</a></li>
556 <li><a href="#how-do-i-convert-a-dataset-to-a-different-type" id="toc-how-do-i-convert-a-dataset-to-a-different-type" class="nav-link" data-scroll-target="#how-do-i-convert-a-dataset-to-a-different-type">How do I convert a dataset to a different type?</a></li>
557 <li><a href="#how-do-i-handle-optional-ndarray-fields" id="toc-how-do-i-handle-optional-ndarray-fields" class="nav-link" data-scroll-target="#how-do-i-handle-optional-ndarray-fields">How do I handle optional NDArray fields?</a></li>
558 <li><a href="#why-is-my-dataset-iteration-slow" id="toc-why-is-my-dataset-iteration-slow" class="nav-link" data-scroll-target="#why-is-my-dataset-iteration-slow">Why is my dataset iteration slow?</a></li>
559 <li><a href="#how-do-i-export-to-parquet" id="toc-how-do-i-export-to-parquet" class="nav-link" data-scroll-target="#how-do-i-export-to-parquet">How do I export to parquet?</a></li>
560 <li><a href="#how-do-i-handle-multiple-shards" id="toc-how-do-i-handle-multiple-shards" class="nav-link" data-scroll-target="#how-do-i-handle-multiple-shards">How do I handle multiple shards?</a></li>
561 <li><a href="#can-i-use-s3-or-other-cloud-storage" id="toc-can-i-use-s3-or-other-cloud-storage" class="nav-link" data-scroll-target="#can-i-use-s3-or-other-cloud-storage">Can I use S3 or other cloud storage?</a></li>
562 <li><a href="#how-do-i-publish-to-atprotoatmosphere" id="toc-how-do-i-publish-to-atprotoatmosphere" class="nav-link" data-scroll-target="#how-do-i-publish-to-atprotoatmosphere">How do I publish to ATProto/Atmosphere?</a></li>
563 <li><a href="#whats-the-difference-between-localindex-and-atmosphereindex" id="toc-whats-the-difference-between-localindex-and-atmosphereindex" class="nav-link" data-scroll-target="#whats-the-difference-between-localindex-and-atmosphereindex">What’s the difference between LocalIndex and AtmosphereIndex?</a></li>
564 </ul></li>
565 <li><a href="#getting-help" id="toc-getting-help" class="nav-link" data-scroll-target="#getting-help">Getting Help</a></li>
566 </ul>
567<div class="toc-actions"><ul><li><a href="https://github.com/your-org/atdata/edit/main/reference/troubleshooting.qmd" class="toc-action"><i class="bi bi-github"></i>Edit this page</a></li><li><a href="https://github.com/your-org/atdata/issues/new" class="toc-action"><i class="bi empty"></i>Report an issue</a></li></ul></div></nav>
568 </div>
569<!-- main -->
570<main class="content" id="quarto-document-content">
571
572
573<header id="title-block-header" class="quarto-title-block default"><nav class="quarto-page-breadcrumbs quarto-title-breadcrumbs d-none d-lg-block" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item"><a href="../reference/architecture.html">Reference</a></li><li class="breadcrumb-item"><a href="../reference/troubleshooting.html">Troubleshooting & FAQ</a></li></ol></nav>
574<div class="quarto-title">
575<h1 class="title">Troubleshooting & FAQ</h1>
576</div>
577
578<div>
579 <div class="description">
580 Common issues and frequently asked questions
581 </div>
582</div>
583
584
585<div class="quarto-title-meta">
586
587
588
589
590 </div>
591
592
593
594</header>
595
596
597<p>This page covers common issues, error messages, and frequently asked questions when working with atdata.</p>
598<section id="common-errors" class="level2">
599<h2 class="anchored" data-anchor-id="common-errors">Common Errors</h2>
600<section id="typeerror-type-object-is-not-subscriptable" class="level3">
601<h3 class="anchored" data-anchor-id="typeerror-type-object-is-not-subscriptable">TypeError: ‘type’ object is not subscriptable</h3>
602<p><strong>Error:</strong></p>
603<pre><code>TypeError: 'type' object is not subscriptable</code></pre>
604<p><strong>Cause:</strong> Using <code>Dataset</code> or <code>SampleBatch</code> without subscripting the type parameter on Python < 3.9, or using an unsubscripted generic.</p>
605<p><strong>Solution:</strong> Always use the subscripted form:</p>
606<div class="sourceCode" id="cb2"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Correct</span></span>
607<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](<span class="st">"data.tar"</span>)</span>
608<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a>batch <span class="op">=</span> SampleBatch[MySample](samples)</span>
609<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a></span>
610<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="co"># Incorrect</span></span>
611<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset(<span class="st">"data.tar"</span>) <span class="co"># Missing type parameter</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
612</section>
613<section id="attributeerror-nonetype-object-has-no-attribute" class="level3">
614<h3 class="anchored" data-anchor-id="attributeerror-nonetype-object-has-no-attribute">AttributeError: ‘NoneType’ object has no attribute…</h3>
615<p><strong>Error:</strong></p>
616<pre><code>AttributeError: 'NoneType' object has no attribute '__args__'</code></pre>
617<p><strong>Cause:</strong> Creating a <code>Dataset</code> or <code>SampleBatch</code> without using the subscripted syntax <code>Class[Type](...)</code>.</p>
618<p><strong>Solution:</strong> These classes use Python’s <code>__orig_class__</code> mechanism to extract type parameters at runtime. You must use:</p>
619<div class="sourceCode" id="cb4"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](url) <span class="co"># Correct</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
620<p>Not:</p>
621<div class="sourceCode" id="cb5"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset(url) <span class="co"># Wrong - no type information</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
622</section>
623<section id="runtimeerror-msgpack-field-not-found-in-sample" class="level3">
624<h3 class="anchored" data-anchor-id="runtimeerror-msgpack-field-not-found-in-sample">RuntimeError: msgpack field not found in sample</h3>
625<p><strong>Error:</strong></p>
626<pre><code>RuntimeError: Malformed sample: 'msgpack' field not found</code></pre>
627<p><strong>Cause:</strong> The tar file contains samples that weren’t written with atdata’s serialization format.</p>
628<p><strong>Solution:</strong> Ensure samples are written using <code>sample.as_wds</code>:</p>
629<div class="sourceCode" id="cb7"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="cf">with</span> wds.writer.TarWriter(<span class="st">"data.tar"</span>) <span class="im">as</span> sink:</span>
630<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a> <span class="cf">for</span> sample <span class="kw">in</span> samples:</span>
631<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a> sink.write(sample.as_wds) <span class="co"># Correct</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
632</section>
633<section id="valueerror-field-type-not-supported" class="level3">
634<h3 class="anchored" data-anchor-id="valueerror-field-type-not-supported">ValueError: Field type not supported</h3>
635<p><strong>Error:</strong></p>
636<pre><code>TypeError: Unsupported type for schema field: <class 'SomeType'></code></pre>
637<p><strong>Cause:</strong> Using an unsupported Python type in a PackableSample field.</p>
638<p><strong>Supported types:</strong></p>
639<table class="caption-top table">
640<thead>
641<tr class="header">
642<th>Python Type</th>
643<th>Notes</th>
644</tr>
645</thead>
646<tbody>
647<tr class="odd">
648<td><code>str</code></td>
649<td>Unicode strings</td>
650</tr>
651<tr class="even">
652<td><code>int</code></td>
653<td>Integers</td>
654</tr>
655<tr class="odd">
656<td><code>float</code></td>
657<td>Floating point</td>
658</tr>
659<tr class="even">
660<td><code>bool</code></td>
661<td>Boolean</td>
662</tr>
663<tr class="odd">
664<td><code>bytes</code></td>
665<td>Binary data</td>
666</tr>
667<tr class="even">
668<td><code>NDArray</code></td>
669<td>Numpy arrays (any dtype)</td>
670</tr>
671<tr class="odd">
672<td><code>list[T]</code></td>
673<td>Lists of primitives</td>
674</tr>
675<tr class="even">
676<td><code>T \| None</code></td>
677<td>Optional fields</td>
678</tr>
679</tbody>
680</table>
681<p><strong>Not supported:</strong> Nested dataclasses, dicts, custom classes.</p>
682</section>
683<section id="keyerror-when-iterating-dataset" class="level3">
684<h3 class="anchored" data-anchor-id="keyerror-when-iterating-dataset">KeyError when iterating dataset</h3>
685<p><strong>Error:</strong></p>
686<pre><code>KeyError: 'msgpack'</code></pre>
687<p><strong>Cause:</strong> The WebDataset tar file structure doesn’t match expected format.</p>
688<p><strong>Solution:</strong> Verify your tar file was created correctly:</p>
689<div class="sourceCode" id="cb10"><pre class="sourceCode bash code-with-copy"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Check tar contents</span></span>
690<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="fu">tar</span> <span class="at">-tvf</span> data.tar <span class="kw">|</span> <span class="fu">head</span> <span class="at">-20</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
691<p>Each sample should have a <code>.msgpack</code> extension in the tar file.</p>
692</section>
693</section>
694<section id="faq" class="level2">
695<h2 class="anchored" data-anchor-id="faq">FAQ</h2>
696<section id="how-do-i-check-the-sample-type-of-a-dataset" class="level3">
697<h3 class="anchored" data-anchor-id="how-do-i-check-the-sample-type-of-a-dataset">How do I check the sample type of a dataset?</h3>
698<div class="sourceCode" id="cb11"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](<span class="st">"data.tar"</span>)</span>
699<span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="bu">print</span>(ds.sample_type) <span class="co"># <class 'MySample'></span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
700</section>
701<section id="how-do-i-convert-a-dataset-to-a-different-type" class="level3">
702<h3 class="anchored" data-anchor-id="how-do-i-convert-a-dataset-to-a-different-type">How do I convert a dataset to a different type?</h3>
703<p>Use the <code>as_type()</code> method with a registered lens:</p>
704<div class="sourceCode" id="cb12"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="at">@atdata.lens</span></span>
705<span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="kw">def</span> my_lens(src: SourceType) <span class="op">-></span> TargetType:</span>
706<span id="cb12-3"><a href="#cb12-3" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> TargetType(field<span class="op">=</span>src.other_field)</span>
707<span id="cb12-4"><a href="#cb12-4" aria-hidden="true" tabindex="-1"></a></span>
708<span id="cb12-5"><a href="#cb12-5" aria-hidden="true" tabindex="-1"></a>ds_view <span class="op">=</span> ds.as_type(TargetType)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
709</section>
710<section id="how-do-i-handle-optional-ndarray-fields" class="level3">
711<h3 class="anchored" data-anchor-id="how-do-i-handle-optional-ndarray-fields">How do I handle optional NDArray fields?</h3>
712<p>Use <code>NDArray | None</code> annotation:</p>
713<div class="sourceCode" id="cb13"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a><span class="at">@atdata.packable</span></span>
714<span id="cb13-2"><a href="#cb13-2" aria-hidden="true" tabindex="-1"></a><span class="kw">class</span> MySample:</span>
715<span id="cb13-3"><a href="#cb13-3" aria-hidden="true" tabindex="-1"></a> required_array: NDArray</span>
716<span id="cb13-4"><a href="#cb13-4" aria-hidden="true" tabindex="-1"></a> optional_array: NDArray <span class="op">|</span> <span class="va">None</span> <span class="op">=</span> <span class="va">None</span></span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
717</section>
718<section id="why-is-my-dataset-iteration-slow" class="level3">
719<h3 class="anchored" data-anchor-id="why-is-my-dataset-iteration-slow">Why is my dataset iteration slow?</h3>
720<p>Common causes:</p>
721<ol type="1">
722<li><strong>Network latency</strong>: Use local caching for remote datasets</li>
723<li><strong>Small batch sizes</strong>: Increase <code>batch_size</code> in <code>ordered()</code> or <code>shuffled()</code></li>
724<li><strong>Shuffle buffer</strong>: For <code>shuffled()</code>, the <code>initial</code> parameter controls buffer size</li>
725</ol>
726<div class="sourceCode" id="cb14"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Larger batches = better throughput</span></span>
727<span id="cb14-2"><a href="#cb14-2" aria-hidden="true" tabindex="-1"></a><span class="cf">for</span> batch <span class="kw">in</span> ds.shuffled(batch_size<span class="op">=</span><span class="dv">64</span>, initial<span class="op">=</span><span class="dv">1000</span>):</span>
728<span id="cb14-3"><a href="#cb14-3" aria-hidden="true" tabindex="-1"></a> ...</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
729</section>
730<section id="how-do-i-export-to-parquet" class="level3">
731<h3 class="anchored" data-anchor-id="how-do-i-export-to-parquet">How do I export to parquet?</h3>
732<div class="sourceCode" id="cb15"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](<span class="st">"data.tar"</span>)</span>
733<span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a>ds.to_parquet(<span class="st">"output.parquet"</span>)</span>
734<span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a></span>
735<span id="cb15-4"><a href="#cb15-4" aria-hidden="true" tabindex="-1"></a><span class="co"># With sample limit (for large datasets)</span></span>
736<span id="cb15-5"><a href="#cb15-5" aria-hidden="true" tabindex="-1"></a>ds.to_parquet(<span class="st">"output.parquet"</span>, maxcount<span class="op">=</span><span class="dv">10000</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
737<div class="callout callout-style-default callout-warning callout-titled">
738<div class="callout-header d-flex align-content-center">
739<div class="callout-icon-container">
740<i class="callout-icon"></i>
741</div>
742<div class="callout-title-container flex-fill">
743Warning
744</div>
745</div>
746<div class="callout-body-container callout-body">
747<p><code>to_parquet()</code> loads the dataset into memory. For very large datasets, use <code>maxcount</code> to limit samples or process in chunks.</p>
748</div>
749</div>
750</section>
751<section id="how-do-i-handle-multiple-shards" class="level3">
752<h3 class="anchored" data-anchor-id="how-do-i-handle-multiple-shards">How do I handle multiple shards?</h3>
753<p>Use WebDataset brace notation:</p>
754<div class="sourceCode" id="cb16"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Single shard</span></span>
755<span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](<span class="st">"data-000000.tar"</span>)</span>
756<span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a></span>
757<span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a><span class="co"># Multiple shards (range)</span></span>
758<span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](<span class="st">"data-{000000..000009}.tar"</span>)</span>
759<span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a></span>
760<span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a><span class="co"># Multiple shards (list)</span></span>
761<span id="cb16-8"><a href="#cb16-8" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](<span class="st">"data-{000000,000005,000009}.tar"</span>)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
762</section>
763<section id="can-i-use-s3-or-other-cloud-storage" class="level3">
764<h3 class="anchored" data-anchor-id="can-i-use-s3-or-other-cloud-storage">Can I use S3 or other cloud storage?</h3>
765<p>Yes, use <code>S3Source</code> for S3-compatible storage:</p>
766<div class="sourceCode" id="cb17"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> atdata <span class="im">import</span> S3Source, Dataset</span>
767<span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a></span>
768<span id="cb17-3"><a href="#cb17-3" aria-hidden="true" tabindex="-1"></a>source <span class="op">=</span> S3Source.from_urls(</span>
769<span id="cb17-4"><a href="#cb17-4" aria-hidden="true" tabindex="-1"></a> [<span class="st">"s3://bucket/data-000000.tar"</span>, <span class="st">"s3://bucket/data-000001.tar"</span>],</span>
770<span id="cb17-5"><a href="#cb17-5" aria-hidden="true" tabindex="-1"></a> endpoint_url<span class="op">=</span><span class="st">"https://s3.example.com"</span>, <span class="co"># Optional for non-AWS S3</span></span>
771<span id="cb17-6"><a href="#cb17-6" aria-hidden="true" tabindex="-1"></a>)</span>
772<span id="cb17-7"><a href="#cb17-7" aria-hidden="true" tabindex="-1"></a></span>
773<span id="cb17-8"><a href="#cb17-8" aria-hidden="true" tabindex="-1"></a>ds <span class="op">=</span> Dataset[MySample](source)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
774</section>
775<section id="how-do-i-publish-to-atprotoatmosphere" class="level3">
776<h3 class="anchored" data-anchor-id="how-do-i-publish-to-atprotoatmosphere">How do I publish to ATProto/Atmosphere?</h3>
777<div class="sourceCode" id="cb18"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="im">from</span> atdata.atmosphere <span class="im">import</span> AtmosphereClient, AtmosphereIndex</span>
778<span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a></span>
779<span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a>client <span class="op">=</span> AtmosphereClient()</span>
780<span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a>client.login(<span class="st">"handle.bsky.social"</span>, <span class="st">"app-password"</span>) <span class="co"># Use app password!</span></span>
781<span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a></span>
782<span id="cb18-6"><a href="#cb18-6" aria-hidden="true" tabindex="-1"></a>index <span class="op">=</span> AtmosphereIndex(client)</span>
783<span id="cb18-7"><a href="#cb18-7" aria-hidden="true" tabindex="-1"></a></span>
784<span id="cb18-8"><a href="#cb18-8" aria-hidden="true" tabindex="-1"></a><span class="co"># Publish schema</span></span>
785<span id="cb18-9"><a href="#cb18-9" aria-hidden="true" tabindex="-1"></a>schema_uri <span class="op">=</span> index.publish_schema(MySample, version<span class="op">=</span><span class="st">"1.0.0"</span>)</span>
786<span id="cb18-10"><a href="#cb18-10" aria-hidden="true" tabindex="-1"></a></span>
787<span id="cb18-11"><a href="#cb18-11" aria-hidden="true" tabindex="-1"></a><span class="co"># Publish dataset</span></span>
788<span id="cb18-12"><a href="#cb18-12" aria-hidden="true" tabindex="-1"></a>entry <span class="op">=</span> index.insert_dataset(ds, name<span class="op">=</span><span class="st">"my-dataset"</span>, schema_ref<span class="op">=</span>schema_uri)</span></code><button title="Copy to Clipboard" class="code-copy-button"><i class="bi"></i></button></pre></div>
789</section>
790<section id="whats-the-difference-between-localindex-and-atmosphereindex" class="level3">
791<h3 class="anchored" data-anchor-id="whats-the-difference-between-localindex-and-atmosphereindex">What’s the difference between LocalIndex and AtmosphereIndex?</h3>
792<table class="caption-top table">
793<thead>
794<tr class="header">
795<th>Feature</th>
796<th>LocalIndex</th>
797<th>AtmosphereIndex</th>
798</tr>
799</thead>
800<tbody>
801<tr class="odd">
802<td>Storage</td>
803<td>Redis + S3</td>
804<td>ATProto PDS</td>
805</tr>
806<tr class="even">
807<td>Discovery</td>
808<td>Local only</td>
809<td>Federated network</td>
810</tr>
811<tr class="odd">
812<td>Auth</td>
813<td>None required</td>
814<td>ATProto account</td>
815</tr>
816<tr class="even">
817<td>Use case</td>
818<td>Development, private data</td>
819<td>Public distribution</td>
820</tr>
821</tbody>
822</table>
823<p>Both implement the <code>AbstractIndex</code> protocol, so code can work with either.</p>
824</section>
825</section>
826<section id="getting-help" class="level2">
827<h2 class="anchored" data-anchor-id="getting-help">Getting Help</h2>
828<ul>
829<li><strong>GitHub Issues</strong>: <a href="https://github.com/your-org/atdata/issues">github.com/your-org/atdata/issues</a></li>
830<li><strong>Documentation</strong>: Check the reference pages for detailed API documentation</li>
831<li><strong>Examples</strong>: See the <code>examples/</code> directory for working code samples</li>
832</ul>
833
834
835</section>
836
837</main> <!-- /main -->
838<script id="quarto-html-after-body" type="application/javascript">
839 window.document.addEventListener("DOMContentLoaded", function (event) {
840 // Ensure there is a toggle, if there isn't float one in the top right
841 if (window.document.querySelector('.quarto-color-scheme-toggle') === null) {
842 const a = window.document.createElement('a');
843 a.classList.add('top-right');
844 a.classList.add('quarto-color-scheme-toggle');
845 a.href = "";
846 a.onclick = function() { try { window.quartoToggleColorScheme(); } catch {} return false; };
847 const i = window.document.createElement("i");
848 i.classList.add('bi');
849 a.appendChild(i);
850 window.document.body.appendChild(a);
851 }
852 setColorSchemeToggle(hasAlternateSentinel())
853 const icon = "";
854 const anchorJS = new window.AnchorJS();
855 anchorJS.options = {
856 placement: 'right',
857 icon: icon
858 };
859 anchorJS.add('.anchored');
860 const isCodeAnnotation = (el) => {
861 for (const clz of el.classList) {
862 if (clz.startsWith('code-annotation-')) {
863 return true;
864 }
865 }
866 return false;
867 }
868 const onCopySuccess = function(e) {
869 // button target
870 const button = e.trigger;
871 // don't keep focus
872 button.blur();
873 // flash "checked"
874 button.classList.add('code-copy-button-checked');
875 var currentTitle = button.getAttribute("title");
876 button.setAttribute("title", "Copied!");
877 let tooltip;
878 if (window.bootstrap) {
879 button.setAttribute("data-bs-toggle", "tooltip");
880 button.setAttribute("data-bs-placement", "left");
881 button.setAttribute("data-bs-title", "Copied!");
882 tooltip = new bootstrap.Tooltip(button,
883 { trigger: "manual",
884 customClass: "code-copy-button-tooltip",
885 offset: [0, -8]});
886 tooltip.show();
887 }
888 setTimeout(function() {
889 if (tooltip) {
890 tooltip.hide();
891 button.removeAttribute("data-bs-title");
892 button.removeAttribute("data-bs-toggle");
893 button.removeAttribute("data-bs-placement");
894 }
895 button.setAttribute("title", currentTitle);
896 button.classList.remove('code-copy-button-checked');
897 }, 1000);
898 // clear code selection
899 e.clearSelection();
900 }
901 const getTextToCopy = function(trigger) {
902 const codeEl = trigger.previousElementSibling.cloneNode(true);
903 for (const childEl of codeEl.children) {
904 if (isCodeAnnotation(childEl)) {
905 childEl.remove();
906 }
907 }
908 return codeEl.innerText;
909 }
910 const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
911 text: getTextToCopy
912 });
913 clipboard.on('success', onCopySuccess);
914 if (window.document.getElementById('quarto-embedded-source-code-modal')) {
915 const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
916 text: getTextToCopy,
917 container: window.document.getElementById('quarto-embedded-source-code-modal')
918 });
919 clipboardModal.on('success', onCopySuccess);
920 }
921 var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
922 var mailtoRegex = new RegExp(/^mailto:/);
923 var filterRegex = new RegExp("https:\/\/github\.com\/your-org\/atdata");
924 var isInternal = (href) => {
925 return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
926 }
927 // Inspect non-navigation links and adorn them if external
928 var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
929 for (var i=0; i<links.length; i++) {
930 const link = links[i];
931 if (!isInternal(link.href)) {
932 // undo the damage that might have been done by quarto-nav.js in the case of
933 // links that we want to consider external
934 if (link.dataset.originalHref !== undefined) {
935 link.href = link.dataset.originalHref;
936 }
937 }
938 }
939 function tippyHover(el, contentFn, onTriggerFn, onUntriggerFn) {
940 const config = {
941 allowHTML: true,
942 maxWidth: 500,
943 delay: 100,
944 arrow: false,
945 appendTo: function(el) {
946 return el.parentElement;
947 },
948 interactive: true,
949 interactiveBorder: 10,
950 theme: 'quarto',
951 placement: 'bottom-start',
952 };
953 if (contentFn) {
954 config.content = contentFn;
955 }
956 if (onTriggerFn) {
957 config.onTrigger = onTriggerFn;
958 }
959 if (onUntriggerFn) {
960 config.onUntrigger = onUntriggerFn;
961 }
962 window.tippy(el, config);
963 }
964 const noterefs = window.document.querySelectorAll('a[role="doc-noteref"]');
965 for (var i=0; i<noterefs.length; i++) {
966 const ref = noterefs[i];
967 tippyHover(ref, function() {
968 // use id or data attribute instead here
969 let href = ref.getAttribute('data-footnote-href') || ref.getAttribute('href');
970 try { href = new URL(href).hash; } catch {}
971 const id = href.replace(/^#\/?/, "");
972 const note = window.document.getElementById(id);
973 if (note) {
974 return note.innerHTML;
975 } else {
976 return "";
977 }
978 });
979 }
980 const xrefs = window.document.querySelectorAll('a.quarto-xref');
981 const processXRef = (id, note) => {
982 // Strip column container classes
983 const stripColumnClz = (el) => {
984 el.classList.remove("page-full", "page-columns");
985 if (el.children) {
986 for (const child of el.children) {
987 stripColumnClz(child);
988 }
989 }
990 }
991 stripColumnClz(note)
992 if (id === null || id.startsWith('sec-')) {
993 // Special case sections, only their first couple elements
994 const container = document.createElement("div");
995 if (note.children && note.children.length > 2) {
996 container.appendChild(note.children[0].cloneNode(true));
997 for (let i = 1; i < note.children.length; i++) {
998 const child = note.children[i];
999 if (child.tagName === "P" && child.innerText === "") {
1000 continue;
1001 } else {
1002 container.appendChild(child.cloneNode(true));
1003 break;
1004 }
1005 }
1006 if (window.Quarto?.typesetMath) {
1007 window.Quarto.typesetMath(container);
1008 }
1009 return container.innerHTML
1010 } else {
1011 if (window.Quarto?.typesetMath) {
1012 window.Quarto.typesetMath(note);
1013 }
1014 return note.innerHTML;
1015 }
1016 } else {
1017 // Remove any anchor links if they are present
1018 const anchorLink = note.querySelector('a.anchorjs-link');
1019 if (anchorLink) {
1020 anchorLink.remove();
1021 }
1022 if (window.Quarto?.typesetMath) {
1023 window.Quarto.typesetMath(note);
1024 }
1025 if (note.classList.contains("callout")) {
1026 return note.outerHTML;
1027 } else {
1028 return note.innerHTML;
1029 }
1030 }
1031 }
1032 for (var i=0; i<xrefs.length; i++) {
1033 const xref = xrefs[i];
1034 tippyHover(xref, undefined, function(instance) {
1035 instance.disable();
1036 let url = xref.getAttribute('href');
1037 let hash = undefined;
1038 if (url.startsWith('#')) {
1039 hash = url;
1040 } else {
1041 try { hash = new URL(url).hash; } catch {}
1042 }
1043 if (hash) {
1044 const id = hash.replace(/^#\/?/, "");
1045 const note = window.document.getElementById(id);
1046 if (note !== null) {
1047 try {
1048 const html = processXRef(id, note.cloneNode(true));
1049 instance.setContent(html);
1050 } finally {
1051 instance.enable();
1052 instance.show();
1053 }
1054 } else {
1055 // See if we can fetch this
1056 fetch(url.split('#')[0])
1057 .then(res => res.text())
1058 .then(html => {
1059 const parser = new DOMParser();
1060 const htmlDoc = parser.parseFromString(html, "text/html");
1061 const note = htmlDoc.getElementById(id);
1062 if (note !== null) {
1063 const html = processXRef(id, note);
1064 instance.setContent(html);
1065 }
1066 }).finally(() => {
1067 instance.enable();
1068 instance.show();
1069 });
1070 }
1071 } else {
1072 // See if we can fetch a full url (with no hash to target)
1073 // This is a special case and we should probably do some content thinning / targeting
1074 fetch(url)
1075 .then(res => res.text())
1076 .then(html => {
1077 const parser = new DOMParser();
1078 const htmlDoc = parser.parseFromString(html, "text/html");
1079 const note = htmlDoc.querySelector('main.content');
1080 if (note !== null) {
1081 // This should only happen for chapter cross references
1082 // (since there is no id in the URL)
1083 // remove the first header
1084 if (note.children.length > 0 && note.children[0].tagName === "HEADER") {
1085 note.children[0].remove();
1086 }
1087 const html = processXRef(null, note);
1088 instance.setContent(html);
1089 }
1090 }).finally(() => {
1091 instance.enable();
1092 instance.show();
1093 });
1094 }
1095 }, function(instance) {
1096 });
1097 }
1098 let selectedAnnoteEl;
1099 const selectorForAnnotation = ( cell, annotation) => {
1100 let cellAttr = 'data-code-cell="' + cell + '"';
1101 let lineAttr = 'data-code-annotation="' + annotation + '"';
1102 const selector = 'span[' + cellAttr + '][' + lineAttr + ']';
1103 return selector;
1104 }
1105 const selectCodeLines = (annoteEl) => {
1106 const doc = window.document;
1107 const targetCell = annoteEl.getAttribute("data-target-cell");
1108 const targetAnnotation = annoteEl.getAttribute("data-target-annotation");
1109 const annoteSpan = window.document.querySelector(selectorForAnnotation(targetCell, targetAnnotation));
1110 const lines = annoteSpan.getAttribute("data-code-lines").split(",");
1111 const lineIds = lines.map((line) => {
1112 return targetCell + "-" + line;
1113 })
1114 let top = null;
1115 let height = null;
1116 let parent = null;
1117 if (lineIds.length > 0) {
1118 //compute the position of the single el (top and bottom and make a div)
1119 const el = window.document.getElementById(lineIds[0]);
1120 top = el.offsetTop;
1121 height = el.offsetHeight;
1122 parent = el.parentElement.parentElement;
1123 if (lineIds.length > 1) {
1124 const lastEl = window.document.getElementById(lineIds[lineIds.length - 1]);
1125 const bottom = lastEl.offsetTop + lastEl.offsetHeight;
1126 height = bottom - top;
1127 }
1128 if (top !== null && height !== null && parent !== null) {
1129 // cook up a div (if necessary) and position it
1130 let div = window.document.getElementById("code-annotation-line-highlight");
1131 if (div === null) {
1132 div = window.document.createElement("div");
1133 div.setAttribute("id", "code-annotation-line-highlight");
1134 div.style.position = 'absolute';
1135 parent.appendChild(div);
1136 }
1137 div.style.top = top - 2 + "px";
1138 div.style.height = height + 4 + "px";
1139 div.style.left = 0;
1140 let gutterDiv = window.document.getElementById("code-annotation-line-highlight-gutter");
1141 if (gutterDiv === null) {
1142 gutterDiv = window.document.createElement("div");
1143 gutterDiv.setAttribute("id", "code-annotation-line-highlight-gutter");
1144 gutterDiv.style.position = 'absolute';
1145 const codeCell = window.document.getElementById(targetCell);
1146 const gutter = codeCell.querySelector('.code-annotation-gutter');
1147 gutter.appendChild(gutterDiv);
1148 }
1149 gutterDiv.style.top = top - 2 + "px";
1150 gutterDiv.style.height = height + 4 + "px";
1151 }
1152 selectedAnnoteEl = annoteEl;
1153 }
1154 };
1155 const unselectCodeLines = () => {
1156 const elementsIds = ["code-annotation-line-highlight", "code-annotation-line-highlight-gutter"];
1157 elementsIds.forEach((elId) => {
1158 const div = window.document.getElementById(elId);
1159 if (div) {
1160 div.remove();
1161 }
1162 });
1163 selectedAnnoteEl = undefined;
1164 };
1165 // Handle positioning of the toggle
1166 window.addEventListener(
1167 "resize",
1168 throttle(() => {
1169 elRect = undefined;
1170 if (selectedAnnoteEl) {
1171 selectCodeLines(selectedAnnoteEl);
1172 }
1173 }, 10)
1174 );
1175 function throttle(fn, ms) {
1176 let throttle = false;
1177 let timer;
1178 return (...args) => {
1179 if(!throttle) { // first call gets through
1180 fn.apply(this, args);
1181 throttle = true;
1182 } else { // all the others get throttled
1183 if(timer) clearTimeout(timer); // cancel #2
1184 timer = setTimeout(() => {
1185 fn.apply(this, args);
1186 timer = throttle = false;
1187 }, ms);
1188 }
1189 };
1190 }
1191 // Attach click handler to the DT
1192 const annoteDls = window.document.querySelectorAll('dt[data-target-cell]');
1193 for (const annoteDlNode of annoteDls) {
1194 annoteDlNode.addEventListener('click', (event) => {
1195 const clickedEl = event.target;
1196 if (clickedEl !== selectedAnnoteEl) {
1197 unselectCodeLines();
1198 const activeEl = window.document.querySelector('dt[data-target-cell].code-annotation-active');
1199 if (activeEl) {
1200 activeEl.classList.remove('code-annotation-active');
1201 }
1202 selectCodeLines(clickedEl);
1203 clickedEl.classList.add('code-annotation-active');
1204 } else {
1205 // Unselect the line
1206 unselectCodeLines();
1207 clickedEl.classList.remove('code-annotation-active');
1208 }
1209 });
1210 }
1211 const findCites = (el) => {
1212 const parentEl = el.parentElement;
1213 if (parentEl) {
1214 const cites = parentEl.dataset.cites;
1215 if (cites) {
1216 return {
1217 el,
1218 cites: cites.split(' ')
1219 };
1220 } else {
1221 return findCites(el.parentElement)
1222 }
1223 } else {
1224 return undefined;
1225 }
1226 };
1227 var bibliorefs = window.document.querySelectorAll('a[role="doc-biblioref"]');
1228 for (var i=0; i<bibliorefs.length; i++) {
1229 const ref = bibliorefs[i];
1230 const citeInfo = findCites(ref);
1231 if (citeInfo) {
1232 tippyHover(citeInfo.el, function() {
1233 var popup = window.document.createElement('div');
1234 citeInfo.cites.forEach(function(cite) {
1235 var citeDiv = window.document.createElement('div');
1236 citeDiv.classList.add('hanging-indent');
1237 citeDiv.classList.add('csl-entry');
1238 var biblioDiv = window.document.getElementById('ref-' + cite);
1239 if (biblioDiv) {
1240 citeDiv.innerHTML = biblioDiv.innerHTML;
1241 }
1242 popup.appendChild(citeDiv);
1243 });
1244 return popup.innerHTML;
1245 });
1246 }
1247 }
1248 });
1249 </script>
1250</div> <!-- /content -->
1251<footer class="footer">
1252 <div class="nav-footer">
1253 <div class="nav-footer-left">
1254<p>Built with <a href="https://quarto.org/">Quarto</a></p>
1255</div>
1256 <div class="nav-footer-center">
1257
1258 <div class="toc-actions d-sm-block d-md-none"><ul><li><a href="https://github.com/your-org/atdata/edit/main/reference/troubleshooting.qmd" class="toc-action"><i class="bi bi-github"></i>Edit this page</a></li><li><a href="https://github.com/your-org/atdata/issues/new" class="toc-action"><i class="bi empty"></i>Report an issue</a></li></ul></div></div>
1259 <div class="nav-footer-right">
1260<p>MIT License</p>
1261</div>
1262 </div>
1263</footer>
1264
1265
1266
1267
1268</body></html>