| <!doctype html><html lang=en-US dir=ltr class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-guide/java/compression" data-has-hydrated=false><head><meta charset=UTF-8><meta name=generator content="Docusaurus v3.10.1"><title data-rh=true>Compression | Apache Fory™</title><meta data-rh=true name=viewport content="width=device-width, initial-scale=1.0"/><meta data-rh=true property=og:url content=https://fory.apache.org/docs/next/guide/java/compression /><meta data-rh=true property=og:locale content=en_US /><meta data-rh=true property=og:locale:alternate content=zh_CN /><meta data-rh=true name=docusaurus_locale content=en-US /><meta data-rh=true name=docsearch:language content=en-US /><meta data-rh=true http-equiv=Content-Security-Policy content="frame-src 'self' https://ghbtns.com/;"/><meta data-rh=true property=og:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true property=og:image:width content=1500 /><meta data-rh=true property=og:image:height content=1500 /><meta data-rh=true name=twitter:card content=summary_large_image /><meta data-rh=true name=twitter:image content=https://fory.apache.org/img/logo.png /><meta data-rh=true name=docusaurus_version content=current /><meta data-rh=true name=docusaurus_tag content=docs-default-current /><meta data-rh=true name=docsearch:version content=current /><meta data-rh=true name=docsearch:docusaurus_tag content=docs-default-current /><meta data-rh=true property=og:title content="Compression | Apache Fory™"/><meta data-rh=true name=description content="This page covers compression options for reducing serialized data size."/><meta data-rh=true property=og:description content="This page covers compression options for reducing serialized data size."/><link data-rh=true rel=icon href=/img/favicon.ico /><link data-rh=true rel=canonical href=https://fory.apache.org/docs/next/guide/java/compression /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/next/guide/java/compression hreflang=en-US /><link data-rh=true rel=alternate href=https://fory.apache.org/zh-CN/docs/next/guide/java/compression hreflang=zh-CN /><link data-rh=true rel=alternate href=https://fory.apache.org/docs/next/guide/java/compression hreflang=x-default /><link rel=alternate type=application/rss+xml href=/blog/rss.xml title="Apache Fory™ RSS Feed"><link rel=alternate type=application/atom+xml href=/blog/atom.xml title="Apache Fory™ Atom Feed"><script type=text/javascript>"fury.apache.org"===window.location.host&&(window.location.href="https://fory.apache.org"),function(){var i=window.location.pathname.split("/").filter(Boolean),o="docs"===i[0]?0:/^[a-z]{2}-[A-Z]{2}$/.test(i[0])&&"docs"===i[1]?1:-1;if(!(o<0)&&"next"===i[o+1]){var t={"introduction/overview":"introduction","introduction/benchmark":"benchmarks","start/install":"start","start/usage":"start","guide/xlang":"object-serialization/xlang","guide/xlang/getting_started":"object-serialization/xlang","guide/xlang/serialization":"object-serialization/xlang","guide/java/json_support":"json","compiler/compiler_guide":"compiler/getting-started","community/development":"development/building"}[i.slice(o+2).join("/")];if(t){var n="/"+i.slice(0,o+2).join("/");window.location.replace(n+"/"+t+"/"+window.location.search)}}}(),function(){var i=window.location.pathname,o=i.split("/").filter(Boolean),t="docs"===o[0]?0:/^[a-z]{2}-[A-Z]{2}$/.test(o[0])&&"docs"===o[1]?1:-1;if(!(t<0)){var n=t+1,a=o[n];if(("next"===a||/^[0-9]+[.][0-9]+(?:[.][0-9]+)?$/.test(a))&&n++,!("docs"!==o[n]||0>["guide","introduction","start"].indexOf(o[n+1]))){o.splice(n,1);var e="/"+o.join("/");i.endsWith("/")&&(e+="/"),window.location.replace(e+window.location.search+window.location.hash)}}}()</script><link rel=stylesheet href=/assets/css/styles.71057b13.css /><script src=/assets/js/runtime~main.f57d1625.js defer></script><script src=/assets/js/main.12b2cba8.js defer></script></head><body><svg style="display: none;"><defs> |
| <symbol id=theme-svg-external-link viewBox="0 0 24 24"><path fill=currentColor d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol> |
| </defs></svg> |
| <script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"light"),document.documentElement.setAttribute("data-theme-choice",t||"light")}(),function(){try{for(var[t,e]of new URLSearchParams(window.location.search).entries())if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id=__docusaurus><div role=region aria-label="Skip to main content"><a class=skipToContent_fXgn href=#__docusaurus_skipToContent_fallback>Skip to main content</a></div><nav aria-label=Main class="theme-layout-navbar navbar navbar--fixed-top"><div class=navbar__inner><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded=false class="navbar__toggle clean-btn" type=button><svg width=30 height=30 viewBox="0 0 30 30" aria-hidden=true><path stroke=currentColor stroke-linecap=round stroke-miterlimit=10 stroke-width=2 d="M4 7h22M4 15h22M4 23h22"/></svg></button><a class=navbar__brand href=/><div class=navbar__logo><img src=/img/fory-logo-light.png alt="Apache Fory™ Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"/><img src=/img/fory-logo-dark.png alt="Apache Fory™ Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"/></div><b class="navbar__title text--truncate"></b></a><a class="navbar__item navbar__link" href=/docs/next/introduction/>Docs</a><a class="navbar__item navbar__link" href=/docs/next/specification/xlang_serialization_spec>Specification</a><a class="navbar__item navbar__link" href=/docs/next/community/>Community</a><a class="navbar__item navbar__link" href=/user>Users</a><a class="navbar__item navbar__link" href=/download>Download</a><a class="navbar__item navbar__link" href=/blog>Blog</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link>ASF</a><ul class=dropdown__menu><li><a href=https://www.apache.org/ target=_blank rel="noopener noreferrer" class=dropdown__link>Foundation</a><li><a href=https://www.apache.org/licenses/ target=_blank rel="noopener noreferrer" class=dropdown__link>License</a><li><a href=https://www.apache.org/events/current-event.html target=_blank rel="noopener noreferrer" class=dropdown__link>Events</a><li><a href=https://privacy.apache.org/policies/privacy-policy-public.html target=_blank rel="noopener noreferrer" class=dropdown__link>Privacy</a><li><a href=https://www.apache.org/security/ target=_blank rel="noopener noreferrer" class=dropdown__link>Security</a><li><a href=https://www.apache.org/foundation/sponsorship.html target=_blank rel="noopener noreferrer" class=dropdown__link>Sponsorship</a><li><a href=https://www.apache.org/foundation/thanks.html target=_blank rel="noopener noreferrer" class=dropdown__link>Thanks</a><li><a href=https://www.apache.org/foundation/policies/conduct.html target=_blank rel="noopener noreferrer" class=dropdown__link>Code of Conduct</a></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class=navbar__link aria-haspopup=true aria-expanded=false role=button href=/docs/next/guide/java/compression>dev</a><ul class=dropdown__menu><li><a aria-current=page class="dropdown__link dropdown__link--active" href=/docs/next/guide/java/compression>dev</a><li><a class=dropdown__link href=/docs/guide/java/compression>1.5.0</a><li><a class=dropdown__link href=/docs/1.4.0/guide/java/compression>1.4.0</a><li><a class=dropdown__link href=/docs/1.3.0/guide/java/compression>1.3.0</a><li><a class=dropdown__link href=/docs/1.2.0/guide/java/compression>1.2.0</a><li><a class=dropdown__link href=/docs/1.1.0/guide/java/compression>1.1.0</a><li><a class=dropdown__link href=/docs/1.0.0/guide/java/compression>1.0.0</a><li><a class=dropdown__link href=/docs/0.17/guide/java/compression>0.17</a><li><a class=dropdown__link href=/docs/0.16/guide/java/compression>0.16</a><li><a class=dropdown__link href=/docs/0.15/guide/java/compression>0.15</a><li><a class=dropdown__link href=/docs/0.14/guide/java/compression>0.14</a><li><a class=dropdown__link href=/docs/0.13/introduction/overview>0.13</a><li><a class=dropdown__link href=/docs/0.12/introduction/overview>0.12</a><li><a class=dropdown__link href=/docs/0.11/introduction/overview>0.11</a><li><a class=dropdown__link href=/docs/0.10/introduction/overview>0.10</a></ul></div><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href=# aria-haspopup=true aria-expanded=false role=button class=navbar__link><svg viewBox="0 0 24 24" width=20 height=20 aria-hidden=true class=iconLanguage_nlXk><path fill=currentColor d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"/></svg>English</a><ul class=dropdown__menu><li><a href=/docs/next/guide/java/compression target=_self rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang=en-US>English</a><li><a href=/zh-CN/docs/next/guide/java/compression target=_self rel="noopener noreferrer" class=dropdown__link lang=zh-CN>简体中文</a></ul></div><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type=button disabled title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill=currentColor d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill=currentColor d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"/></svg><svg viewBox="0 0 24 24" width=24 height=24 aria-hidden=true class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill=currentColor d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"/></svg></button></div><div class=navbarSearchContainer_Bca1><div class=navbar__search><span aria-label="expand searchbar" role=button class=search-icon tabindex=0></span><input id=search_input_react type=search placeholder=Loading... aria-label=Search class="navbar__search-input search-bar" disabled/></div></div></div></div><div role=presentation class=navbar-sidebar__backdrop></div></nav><div id=__docusaurus_skipToContent_fallback class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class=docsWrapper_hBAB><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type=button></button><div class=docRoot_UBD9><main class="docMainContainer_TBSr docMainContainerEnhanced_lQrH"><div class="container padding-top--md padding-bottom--lg"><div class=row><div class="col docItemCol_VOVn"><div class="theme-doc-version-banner alert alert--warning margin-bottom--md" role=alert><div>This is unreleased documentation for <!-- -->Apache Fory™<!-- --> <b>dev</b> version.</div><div class=margin-top--md>For up-to-date documentation, see the <b><a href=/docs/guide/java/compression>latest version</a></b> (<!-- -->1.5.0<!-- -->).</div></div><div class=docItemContainer_Djhp><article><span class="theme-doc-version-badge badge badge--secondary">Version: dev</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type=button class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Compression</h1></header><p>This page covers compression options for reducing serialized data size.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=integer-compression>Integer Compression<a href=#integer-compression class=hash-link aria-label="Direct link to Integer Compression" title="Direct link to Integer Compression" translate=no></a></h2> |
| <p><code>ForyBuilder#withIntCompressed</code>/<code>ForyBuilder#withLongCompressed</code> can be used to compress int/long for smaller size. Normally compressing int is enough.</p> |
| <p>Both compression options are enabled by default. If the serialized size is not important (for example, you use FlatBuffers for serialization before, which doesn't compress anything), then you should disable compression. If your data are all numbers, the compression may bring 80% performance regression.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=int-compression>Int Compression<a href=#int-compression class=hash-link aria-label="Direct link to Int Compression" title="Direct link to Int Compression" translate=no></a></h3> |
| <p>For int compression, Fory uses 1~5 bytes for encoding. The first bit in every byte indicates whether there is a next byte. If the first bit is set, then the next byte will be read until the first bit of the next byte is unset.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=long-compression>Long Compression<a href=#long-compression class=hash-link aria-label="Direct link to Long Compression" title="Direct link to Long Compression" translate=no></a></h3> |
| <p>For long compression, Fory supports two encodings:</p> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=sli-small-long-as-int-encoding-default>SLI (Small Long as Int) Encoding (Default)<a href=#sli-small-long-as-int-encoding-default class=hash-link aria-label="Direct link to SLI (Small Long as Int) Encoding (Default)" title="Direct link to SLI (Small Long as Int) Encoding (Default)" translate=no></a></h4> |
| <ul> |
| <li class="">If long is in <code>[-1073741824, 1073741823]</code>, encode as 4 bytes int: <code>| little-endian: ((int) value) << 1 |</code></li> |
| <li class="">Otherwise write as 9 bytes: <code>| 0b1 | little-endian 8bytes long |</code></li> |
| </ul> |
| <h4 class="anchor anchorTargetStickyNavbar_Vzrq" id=pvl-progressive-variable-length-long-encoding>PVL (Progressive Variable-length Long) Encoding<a href=#pvl-progressive-variable-length-long-encoding class=hash-link aria-label="Direct link to PVL (Progressive Variable-length Long) Encoding" title="Direct link to PVL (Progressive Variable-length Long) Encoding" translate=no></a></h4> |
| <ul> |
| <li class="">First bit in every byte indicates whether there is a next byte. If first bit is set, then next byte will be read until first bit of next byte is unset.</li> |
| <li class="">Negative numbers will be converted to positive numbers by <code>(v << 1) ^ (v >> 63)</code> to reduce cost of small negative numbers.</li> |
| </ul> |
| <p>If a number is of <code>long</code> type but can't be represented by smaller bytes mostly, the compression won't get good enough results—not worthy compared to performance cost. Maybe you should try to disable long compression if you find it didn't bring much space savings.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=array-compression>Array Compression<a href=#array-compression class=hash-link aria-label="Direct link to Array Compression" title="Direct link to Array Compression" translate=no></a></h2> |
| <p>Fory can compress primitive arrays (<code>int[]</code> and <code>long[]</code>) when every value fits in a narrower primitive type. JDK 8 through 15 use scalar range analysis. On JDK 16 and later, the multi-release <code>fory-core</code> JAR automatically selects the Vector API implementation.</p> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=how-array-compression-works>How Array Compression Works<a href=#how-array-compression-works class=hash-link aria-label="Direct link to How Array Compression Works" title="Direct link to How Array Compression Works" translate=no></a></h3> |
| <p>Array compression analyzes arrays to determine if values can be stored using fewer bytes:</p> |
| <ul> |
| <li class=""><strong><code>int[]</code> → <code>byte[]</code></strong>: When all values are in range [-128, 127] (75% size reduction)</li> |
| <li class=""><strong><code>int[]</code> → <code>short[]</code></strong>: When all values are in range [-32768, 32767] (50% size reduction)</li> |
| <li class=""><strong><code>long[]</code> → <code>int[]</code></strong>: When all values fit in integer range (50% size reduction)</li> |
| </ul> |
| <h3 class="anchor anchorTargetStickyNavbar_Vzrq" id=configuration-and-registration>Configuration and Registration<a href=#configuration-and-registration class=hash-link aria-label="Direct link to Configuration and Registration" title="Direct link to Configuration and Registration" translate=no></a></h3> |
| <p>To enable array compression, you must explicitly register the serializers:</p> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token class-name">Fory</span><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withXlang</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Enable int array compression</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withIntArrayCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token comment" style=color:#999988;font-style:italic>// Enable long array compression</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withLongArrayCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// You must explicitly register compressed array serializers</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">CompressedArraySerializers</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>registerSerializers</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <p>Compressed array serializers are included in <code>fory-core</code>. When running on JDK 16 or later, resolve the incubator Vector API module when starting the application:</p> |
| <div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token function" style=color:#d73a49>java</span><span class="token plain"> --add-modules</span><span class="token operator" style=color:#393A34>=</span><span class="token plain">jdk.incubator.vector </span><span class="token punctuation" style=color:#393A34>..</span><span class="token plain">.</span><br/></div></code></pre></div></div> |
| <p>No registration or configuration change is required when moving between the scalar and Vector implementations. They make the same compression decisions and use the same serialized format.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=string-compression>String Compression<a href=#string-compression class=hash-link aria-label="Direct link to String Compression" title="Direct link to String Compression" translate=no></a></h2> |
| <p>String compression can be enabled via <code>ForyBuilder#withStringCompressed(true)</code>. This is disabled by default.</p> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=configuration-summary>Configuration Summary<a href=#configuration-summary class=hash-link aria-label="Direct link to Configuration Summary" title="Direct link to Configuration Summary" translate=no></a></h2> |
| <table><thead><tr><th>Option<th>Description<th>Default<tbody><tr><td><code>compressInt</code><td>Enable int compression<td><code>true</code><tr><td><code>compressLong</code><td>Enable long compression<td><code>true</code><tr><td><code>compressIntArray</code><td>Enable int array width compression<td><code>false</code><tr><td><code>compressLongArray</code><td>Enable long array width compression<td><code>false</code><tr><td><code>compressString</code><td>Enable string compression<td><code>false</code></table> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=performance-considerations>Performance Considerations<a href=#performance-considerations class=hash-link aria-label="Direct link to Performance Considerations" title="Direct link to Performance Considerations" translate=no></a></h2> |
| <ol> |
| <li class=""><strong>Disable compression for numeric-heavy data</strong>: If your data is mostly numbers, compression overhead may not be worth it</li> |
| <li class=""><strong>Array compression implementation is JDK-specific</strong>: JDK 8 through 15 use scalar range analysis; JDK 16 and later automatically select the Vector API implementation</li> |
| <li class=""><strong>Long compression may not help large values</strong>: If most longs can't fit in smaller representations, disable it</li> |
| <li class=""><strong>String compression has overhead</strong>: Only enable if strings are highly compressible</li> |
| </ol> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=example-configuration>Example Configuration<a href=#example-configuration class=hash-link aria-label="Direct link to Example Configuration" title="Direct link to Example Configuration" translate=no></a></h2> |
| <div class="language-java codeBlockContainer_Ckt0 theme-code-block" style=--prism-color:#393A34;--prism-background-color:#f6f8fa><div class=codeBlockContent_QJqH><pre tabindex=0 class="prism-code language-java codeBlock_bY9V thin-scrollbar" style=color:#393A34;background-color:#f6f8fa><code class=codeBlockLines_e6Vv><div class=token-line style=color:#393A34><span class="token comment" style=color:#999988;font-style:italic>// For mostly numeric data - disable compression</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Fory</span><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withXlang</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withIntCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withLongCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain" style=display:inline-block></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token comment" style=color:#999988;font-style:italic>// For mixed data with arrays - enable array compression</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">Fory</span><span class="token plain"> fory </span><span class="token operator" style=color:#393A34>=</span><span class="token plain"> </span><span class="token class-name">Fory</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>builder</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withXlang</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>false</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withIntCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withLongCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withIntArrayCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>withLongArrayCompressed</span><span class="token punctuation" style=color:#393A34>(</span><span class="token boolean" style=color:#36acaa>true</span><span class="token punctuation" style=color:#393A34>)</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"> </span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>build</span><span class="token punctuation" style=color:#393A34>(</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><span class="token plain"></span><br/></div><div class=token-line style=color:#393A34><span class="token plain"></span><span class="token class-name">CompressedArraySerializers</span><span class="token punctuation" style=color:#393A34>.</span><span class="token function" style=color:#d73a49>registerSerializers</span><span class="token punctuation" style=color:#393A34>(</span><span class="token plain">fory</span><span class="token punctuation" style=color:#393A34>)</span><span class="token punctuation" style=color:#393A34>;</span><br/></div></code></pre></div></div> |
| <h2 class="anchor anchorTargetStickyNavbar_Vzrq" id=related-topics>Related Topics<a href=#related-topics class=hash-link aria-label="Direct link to Related Topics" title="Direct link to Related Topics" translate=no></a></h2> |
| <ul> |
| <li class=""><a class="" href=/docs/next/guide/java/configuration>Configuration</a> - All ForyBuilder options</li> |
| <li class=""><a class="" href=/docs/next/guide/java/advanced_features>Advanced Features</a> - Memory management</li> |
| </ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href=https://github.com/apache/fory-site/tree/main/docs/guide/java/compression.md target=_blank rel="noopener noreferrer" class=theme-edit-this-page><svg fill=currentColor height=20 width=20 viewBox="0 0 40 40" class=iconEdit_Z9Sw aria-hidden=true><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"/></g></svg>Edit this page</a></div><div class="col lastUpdated_JAkA"></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href=#integer-compression class="table-of-contents__link toc-highlight">Integer Compression</a><ul><li><a href=#int-compression class="table-of-contents__link toc-highlight">Int Compression</a><li><a href=#long-compression class="table-of-contents__link toc-highlight">Long Compression</a></ul><li><a href=#array-compression class="table-of-contents__link toc-highlight">Array Compression</a><ul><li><a href=#how-array-compression-works class="table-of-contents__link toc-highlight">How Array Compression Works</a><li><a href=#configuration-and-registration class="table-of-contents__link toc-highlight">Configuration and Registration</a></ul><li><a href=#string-compression class="table-of-contents__link toc-highlight">String Compression</a><li><a href=#configuration-summary class="table-of-contents__link toc-highlight">Configuration Summary</a><li><a href=#performance-considerations class="table-of-contents__link toc-highlight">Performance Considerations</a><li><a href=#example-configuration class="table-of-contents__link toc-highlight">Example Configuration</a><li><a href=#related-topics class="table-of-contents__link toc-highlight">Related Topics</a></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Community</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://lists.apache.org/list.html?dev@fory.apache.org target=_blank rel="noopener noreferrer" class=footer__link-item>Mailing list<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://join.slack.com/t/fory-project/shared_invite/zt-1u8soj4qc-ieYEu7ciHOqA2mo47llS8A target=_blank rel="noopener noreferrer" class=footer__link-item>Slack<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://twitter.com/ApacheFory target=_blank rel="noopener noreferrer" class=footer__link-item>Twitter<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Docs</div><ul class="footer__items clean-list"><li class=footer__item><a class=footer__link-item href=/docs/start/install>Install</a><li class=footer__item><a class=footer__link-item href=/docs/start/usage>Usage</a><li class=footer__item><a class=footer__link-item href=/docs/introduction/benchmark>Benchmark</a></ul></div><div class="theme-layout-footer-column col footer__col"><div class=footer__title>Repositories</div><ul class="footer__items clean-list"><li class=footer__item><a href=https://github.com/apache/fory target=_blank rel="noopener noreferrer" class=footer__link-item>Apache Fory™<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a><li class=footer__item><a href=https://github.com/apache/fory-site target=_blank rel="noopener noreferrer" class=footer__link-item>Website<svg width=13.5 height=13.5 aria-label="(opens in new tab)" class=iconExternalLink_nPIU><use href=#theme-svg-external-link /></svg></a></ul></div></div><div class="footer__bottom text--center"><div class=margin-bottom--sm><a href=https://apache.org/ rel="noopener noreferrer" class=footerLogoLink_BH7S><img src=/img/asf_logo.svg alt="ASF Logo" class="footer__logo themedComponent_mlkZ themedComponent--light_NVdE" width=200 /><img src=/img/asf_logo.svg alt="ASF Logo" class="footer__logo themedComponent_mlkZ themedComponent--dark_xIcU" width=200 /></a></div><div class=footer__copyright><div> |
| <p> |
| Copyright © 2026 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. <br/> |
| Apache Fory, Fory, Apache, the Apache Logo and the Apache Fory logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. |
| </p> |
| </div></div></div></div></footer></div></body> |
