blob: 525f13f1aa6bebe9b4f8ad2d52838e9696628aae [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Namespace Lucene.Net.Documents
| Apache Lucene.NET 4.8.0-beta00010 Documentation </title>
<meta name="viewport" content="width=device-width">
<meta name="title" content="Namespace Lucene.Net.Documents
| Apache Lucene.NET 4.8.0-beta00010 Documentation ">
<meta name="generator" content="docfx 2.56.0.0">
<link rel="shortcut icon" href="https://lucenenet.apache.org/docs/4.8.0-beta00009/logo/favicon.ico">
<link rel="stylesheet" href="https://lucenenet.apache.org/docs/4.8.0-beta00009/styles/docfx.vendor.css">
<link rel="stylesheet" href="https://lucenenet.apache.org/docs/4.8.0-beta00009/styles/docfx.css">
<link rel="stylesheet" href="https://lucenenet.apache.org/docs/4.8.0-beta00009/styles/main.css">
<meta property="docfx:navrel" content="toc.html">
<meta property="docfx:tocrel" content="core/toc.html">
<meta property="docfx:rel" content="https://lucenenet.apache.org/docs/4.8.0-beta00009/">
</head>
<body data-spy="scroll" data-target="#affix" data-offset="120">
<div id="wrapper">
<header>
<nav id="autocollapse" class="navbar ng-scope" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/">
<img id="logo" class="svg" src="https://lucenenet.apache.org/docs/4.8.0-beta00009/logo/lucene-net-color.png" alt="">
</a>
</div>
<div class="collapse navbar-collapse" id="navbar">
<form class="navbar-form navbar-right" role="search" id="search">
<div class="form-group">
<input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
</div>
</form>
</div>
</div>
</nav>
<div class="subnav navbar navbar-default">
<div class="container hide-when-search">
<ul class="level0 breadcrumb">
<li>
<a href="https://lucenenet.apache.org/docs/4.8.0-beta00009/">API</a>
<span id="breadcrumb">
<ul class="breadcrumb">
<li></li>
</ul>
</span>
</li>
</ul>
</div>
</div>
</header>
<div class="container body-content">
<div id="search-results">
<div class="search-list"></div>
<div class="sr-items">
<p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
</div>
<ul id="pagination"></ul>
</div>
</div>
<div role="main" class="container body-content hide-when-search">
<div class="sidenav hide-when-search">
<a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
<div class="sidetoggle collapse" id="sidetoggle">
<div id="sidetoc"></div>
</div>
</div>
<div class="article row grid-right">
<div class="col-md-10">
<article class="content wrap" id="_content" data-uid="Lucene.Net.Documents">
<h1 id="Lucene_Net_Documents" data-uid="Lucene.Net.Documents" class="text-break">Namespace Lucene.Net.Documents
</h1>
<div class="markdown level0 summary"><!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>The logical representation of a <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> for indexing and searching.</p>
<p>The document package provides the user level logical representation of content to be indexed and searched. The package also provides utilities for working with <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a>s and &lt;xref:Lucene.Net.Index.IndexableField&gt;s.</p>
<h2 id="document-and-indexablefield">Document and IndexableField</h2>
<p>A <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> is a collection of &lt;xref:Lucene.Net.Index.IndexableField&gt;s. A &lt;xref:Lucene.Net.Index.IndexableField&gt; is a logical representation of a user&#39;s content that needs to be indexed or stored. &lt;xref:Lucene.Net.Index.IndexableField&gt;s have a number of properties that tell Lucene how to treat the content (like indexed, tokenized, stored, etc.) See the <a class="xref" href="Lucene.Net.Documents.Field.html">Field</a> implementation of &lt;xref:Lucene.Net.Index.IndexableField&gt; for specifics on these properties. </p>
<p>Note: it is common to refer to <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a>s having <a class="xref" href="Lucene.Net.Documents.Field.html">Field</a>s, even though technically they have &lt;xref:Lucene.Net.Index.IndexableField&gt;s.</p>
<h2 id="working-with-documents">Working with Documents</h2>
<p>First and foremost, a <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> is something created by the user application. It is your job to create Documents based on the content of the files you are working with in your application (Word, txt, PDF, Excel or any other format.) How this is done is completely up to you. That being said, there are many tools available in other projects that can make the process of taking a file and converting it into a Lucene <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a>. </p>
<p>The <a class="xref" href="Lucene.Net.Documents.DateTools.html">DateTools</a> is a utility class to make dates and times searchable (remember, Lucene only searches text). &lt;xref:Lucene.Net.Documents.IntField&gt;, &lt;xref:Lucene.Net.Documents.LongField&gt;, &lt;xref:Lucene.Net.Documents.FloatField&gt; and <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a> are a special helper class to simplify indexing of numeric values (and also dates) for fast range range queries with <a class="xref" href="Lucene.Net.Search.NumericRangeQuery.html">NumericRangeQuery</a> (using a special sortable string representation of numeric values).</p>
</div>
<div class="markdown level0 conceptual"></div>
<div class="markdown level0 remarks"></div>
<h3 id="classes">Classes
</h3>
<h4><a class="xref" href="Lucene.Net.Documents.BinaryDocValuesField.html">BinaryDocValuesField</a></h4>
<section><p>Field that stores a per-document <a class="xref" href="Lucene.Net.Util.BytesRef.html">BytesRef</a> value.
<p>
The values are stored directly with no sharing, which is a good fit when
the fields don&apos;t share (many) values, such as a title field. If values
may be shared and sorted it&apos;s better to use <a class="xref" href="Lucene.Net.Documents.SortedDocValuesField.html">SortedDocValuesField</a>.
Here&apos;s an example usage:</p>
<pre><code> document.Add(new BinaryDocValuesField(name, new BytesRef(&quot;hello&quot;)));</code></pre>
<p><p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.ByteDocValuesField.html">ByteDocValuesField</a></h4>
<section><p>Field that stores a per-document <span class="xref">System.Byte</span> value for scoring,
sorting or value retrieval. Here&apos;s an example usage:</p>
<pre><code> document.Add(new ByteDocValuesField(name, (byte) 22));</code></pre>
<p><p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.CompressionTools.html">CompressionTools</a></h4>
<section><p>Simple utility class providing static methods to
compress and decompress binary data for stored fields.
this class uses the <span class="xref">System.IO.Compression.DeflateStream</span>
class to compress and decompress.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.DateTools.html">DateTools</a></h4>
<section><p>Provides support for converting dates to strings and vice-versa.
The strings are structured so that lexicographic sorting orders
them by date, which makes them suitable for use as field values
and search terms.</p>
<p><p>This class also helps you to limit the resolution of your dates. Do not
save dates with a finer resolution than you really need, as then
<a class="xref" href="Lucene.Net.Search.TermRangeQuery.html">TermRangeQuery</a> and <a class="xref" href="Lucene.Net.Search.PrefixQuery.html">PrefixQuery</a> will require more memory and become slower.</p>
<p><p>
Another approach is <a class="xref" href="Lucene.Net.Util.NumericUtils.html">NumericUtils</a>, which provides
a sortable binary representation (prefix encoded) of numeric values, which
date/time are.</p>
<p>For indexing a <span class="xref">System.DateTime</span>, just get the <span class="xref">System.DateTime.Ticks</span> and index
this as a numeric value with <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a> and use <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a>
to query it.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.DerefBytesDocValuesField.html">DerefBytesDocValuesField</a></h4>
<section><p>Field that stores
a per-document <a class="xref" href="Lucene.Net.Util.BytesRef.html">BytesRef</a> value. Here&apos;s an example usage:</p>
<pre><code> document.Add(new DerefBytesDocValuesField(name, new BytesRef(&quot;hello&quot;)));</code></pre>
<p><p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Document.html">Document</a></h4>
<section><p>Documents are the unit of indexing and search.
<p>
A Document is a set of fields. Each field has a name and a textual value.
A field may be stored (<a class="xref" href="Lucene.Net.Index.IIndexableFieldType.html#Lucene_Net_Index_IIndexableFieldType_IsStored">IsStored</a>) with the document, in which
case it is returned with search hits on the document. Thus each document
should typically contain one or more stored fields which uniquely identify
it.
<p>
Note that fields which are <em>not</em> <a class="xref" href="Lucene.Net.Index.IIndexableFieldType.html#Lucene_Net_Index_IIndexableFieldType_IsStored">IsStored</a> are
<em>not</em> available in documents retrieved from the index, e.g. with
<a class="xref" href="Lucene.Net.Search.ScoreDoc.html#Lucene_Net_Search_ScoreDoc_Doc">Doc</a> or <a class="xref" href="Lucene.Net.Index.IndexReader.html#Lucene_Net_Index_IndexReader_Document_System_Int32_">Document(Int32)</a>.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.DocumentStoredFieldVisitor.html">DocumentStoredFieldVisitor</a></h4>
<section><p>A <a class="xref" href="Lucene.Net.Index.StoredFieldVisitor.html">StoredFieldVisitor</a> that creates a
<a class="xref" href="Lucene.Net.Documents.DocumentStoredFieldVisitor.html#Lucene_Net_Documents_DocumentStoredFieldVisitor_Document">Document</a> containing all stored fields, or only specific
requested fields provided to <a class="xref" href="Lucene.Net.Documents.DocumentStoredFieldVisitor.html#Lucene_Net_Documents_DocumentStoredFieldVisitor__ctor_System_Collections_Generic_ISet_System_String__">DocumentStoredFieldVisitor(ISet&lt;String&gt;)</a>.
<p>
This is used by <a class="xref" href="Lucene.Net.Index.IndexReader.html#Lucene_Net_Index_IndexReader_Document_System_Int32_">Document(Int32)</a> to load a
document.</p>
<div class="lucene-block lucene-experimental">This is a Lucene.NET EXPERIMENTAL API, use at your own risk</div></section>
<h4><a class="xref" href="Lucene.Net.Documents.DoubleDocValuesField.html">DoubleDocValuesField</a></h4>
<section><p>Syntactic sugar for encoding doubles as <a class="xref" href="Lucene.Net.Index.NumericDocValues.html">NumericDocValues</a>
via <span class="xref">J2N.BitConversion.DoubleToRawInt64Bits(System.Double)</span>.
<p>
Per-document double values can be retrieved via
<a class="xref" href="Lucene.Net.Search.IFieldCache.html#Lucene_Net_Search_IFieldCache_GetDoubles_Lucene_Net_Index_AtomicReader_System_String_System_Boolean_">GetDoubles(AtomicReader, String, Boolean)</a>.
<p>
<strong>NOTE</strong>: In most all cases this will be rather inefficient,
requiring eight bytes per document. Consider encoding double
values yourself with only as much precision as you require.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a></h4>
<section><p>
Field that indexes <span class="xref">System.Double</span> values
for efficient range filtering and sorting. Here&apos;s an example usage:
<pre><code>document.Add(new DoubleField(name, 6.0, Field.Store.NO));</code></pre>
For optimal performance, re-use the <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a> and
<a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> instance for more than one document:
<pre><code> DoubleField field = new DoubleField(name, 0.0, Field.Store.NO);
Document document = new Document();
document.Add(field);
for (all documents)
{
...
field.SetDoubleValue(value)
writer.AddDocument(document);
...
}</code></pre>
See also <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>, <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>,
<a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>.</p>
<p>To perform range querying or filtering against a
<a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>, use <a class="xref" href="Lucene.Net.Search.NumericRangeQuery.html">NumericRangeQuery</a> or
<a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>. To sort according to a
<a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>, use the normal numeric sort types, eg
<a class="xref" href="Lucene.Net.Search.SortFieldType.html#Lucene_Net_Search_SortFieldType_DOUBLE">DOUBLE</a>. <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>
values can also be loaded directly from <a class="xref" href="Lucene.Net.Search.IFieldCache.html">IFieldCache</a>.</p>
<p>You may add the same field name as an <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a> to
the same document more than once. Range querying and
filtering will be the logical OR of all values; so a range query
will hit all documents that have at least one value in
the range. However sort behavior is not defined. If you need to sort,
you should separately index a single-valued <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>.</p>
<p>A <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a> will consume somewhat more disk space
in the index than an ordinary single-valued field.
However, for a typical index that includes substantial
textual content per document, this increase will likely
be in the noise. </p>
<p>Within Lucene, each numeric value is indexed as a
<em>trie</em> structure, where each term is logically
assigned to larger and larger pre-defined brackets (which
are simply lower-precision representations of the value).
The step size between each successive bracket is called the
<code>precisionStep</code>, measured in bits. Smaller
<code>precisionStep</code> values result in larger number
of brackets, which consumes more disk space in the index
but may result in faster range search performance. The
default value, 4, was selected for a reasonable tradeoff
of disk space consumption versus performance. You can
create a custom <a class="xref" href="Lucene.Net.Documents.FieldType.html">FieldType</a> and invoke the
<a class="xref" href="Lucene.Net.Documents.FieldType.html#Lucene_Net_Documents_FieldType_NumericPrecisionStep">NumericPrecisionStep</a> setter if you&apos;d
like to change the value. Note that you must also
specify a congruent value when creating
<a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a> or <a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>.
For low cardinality fields larger precision steps are good.
If the cardinality is &lt; 100, it is fair
to use <span class="xref">System.Int32.MaxValue</span>, which produces one
term per value.</p>
<p>For more information on the internals of numeric trie
indexing, including the <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html#Lucene_Net_Search_NumericRangeQuery_1_PrecisionStep">PrecisionStep</a> (<a href="../search/NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>)
configuration, see <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a>. The format of
indexed values is described in <a class="xref" href="Lucene.Net.Util.NumericUtils.html">NumericUtils</a>.</p>
<p>If you only need to sort by numeric value, and never
run range querying/filtering, you can index using a
<code>precisionStep</code> of <span class="xref">System.Int32.MaxValue</span>.
this will minimize disk space consumed. </p>
<p>More advanced users can instead use
<a class="xref" href="Lucene.Net.Analysis.NumericTokenStream.html">NumericTokenStream</a> directly, when indexing numbers. This
class is a wrapper around this token stream type for
easier, more intuitive usage.</p>
<p>@since 2.9</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.html">Field</a></h4>
<section><p>Expert: directly create a field for a document. Most
users should use one of the sugar subclasses: <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>,
<a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>, <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>, <a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>,
<a class="xref" href="Lucene.Net.Documents.BinaryDocValuesField.html">BinaryDocValuesField</a>, <a class="xref" href="Lucene.Net.Documents.NumericDocValuesField.html">NumericDocValuesField</a>,
<a class="xref" href="Lucene.Net.Documents.SortedDocValuesField.html">SortedDocValuesField</a>, <a class="xref" href="Lucene.Net.Documents.StringField.html">StringField</a>,
<a class="xref" href="Lucene.Net.Documents.TextField.html">TextField</a>, <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a>.</p>
<p><p> A field is a section of a <a class="xref" href="Lucene.Net.Documents.Document.html">Document</a>. Each field has three
parts: name, type and value. Values may be text
(<span class="xref">System.String</span>, <span class="xref">System.IO.TextReader</span> or pre-analyzed <a class="xref" href="Lucene.Net.Analysis.TokenStream.html">TokenStream</a>), binary
(<span class="xref">byte[]</span>), or numeric (<span class="xref">System.Int32</span>, <span class="xref">System.Int64</span>, <span class="xref">System.Single</span>, or <span class="xref">System.Double</span>).
Fields are optionally stored in the
index, so that they may be returned with hits on the document.</p>
<p><p>
NOTE: the field type is an <a class="xref" href="Lucene.Net.Index.IIndexableFieldType.html">IIndexableFieldType</a>. Making changes
to the state of the <a class="xref" href="Lucene.Net.Index.IIndexableFieldType.html">IIndexableFieldType</a> will impact any
Field it is used in. It is strongly recommended that no
changes be made after <a class="xref" href="Lucene.Net.Documents.Field.html">Field</a> instantiation.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Byte.html">Field.Byte</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Double.html">Field.Double</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Int16.html">Field.Int16</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Int32.html">Field.Int32</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Int64.html">Field.Int64</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Number.html">Field.Number</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Single.html">Field.Single</a></h4>
<section></section>
<h4><a class="xref" href="Lucene.Net.Documents.FieldExtensions.html">FieldExtensions</a></h4>
<section><p>LUCENENET specific extension methods to add functionality to enumerations
that mimic Lucene</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.FieldType.html">FieldType</a></h4>
<section><p>Describes the properties of a field.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Int16DocValuesField.html">Int16DocValuesField</a></h4>
<section><p>
Field that stores a per-document <span class="xref">System.Int16</span> value for scoring,
sorting or value retrieval. Here&apos;s an example usage:
<pre><code> document.Add(new Int16DocValuesField(name, (short) 22));</code></pre>
</p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.
</p>
<p>
NOTE: This was ShortDocValuesField in Lucene
</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Int32DocValuesField.html">Int32DocValuesField</a></h4>
<section><p>Field that stores a per-document <span class="xref">System.Int32</span> value for scoring,
sorting or value retrieval. Here&apos;s an example usage:</p>
<pre><code> document.Add(new Int32DocValuesField(name, 22));</code></pre>
<p>If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.
<p>
NOTE: This was IntDocValuesField in Lucene</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a></h4>
<section><p>
Field that indexes <span class="xref">System.Int32</span> values
for efficient range filtering and sorting. Here&apos;s an example usage:
<pre><code> document.Add(new Int32Field(name, 6, Field.Store.NO));</code></pre>
For optimal performance, re-use the <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a> and
<a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> instance for more than one document:
<pre><code> Int32Field field = new Int32Field(name, 6, Field.Store.NO);
Document document = new Document();
document.Add(field);
for (all documents)
{
...
field.SetInt32Value(value)
writer.AddDocument(document);
...
}</code></pre>
See also <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>, <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>,
<a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>.</p>
<p>To perform range querying or filtering against a
<a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>, use <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a> or
<a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>. To sort according to a
<a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>, use the normal numeric sort types, eg
<a class="xref" href="Lucene.Net.Search.SortFieldType.html#Lucene_Net_Search_SortFieldType_INT32">INT32</a>. <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>
values can also be loaded directly from <a class="xref" href="Lucene.Net.Search.IFieldCache.html">IFieldCache</a>.</p>
<p>You may add the same field name as an <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a> to
the same document more than once. Range querying and
filtering will be the logical OR of all values; so a range query
will hit all documents that have at least one value in
the range. However sort behavior is not defined. If you need to sort,
you should separately index a single-valued <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>.</p>
<p>An <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a> will consume somewhat more disk space
in the index than an ordinary single-valued field.
However, for a typical index that includes substantial
textual content per document, this increase will likely
be in the noise. </p>
<p>Within Lucene, each numeric value is indexed as a
<em>trie</em> structure, where each term is logically
assigned to larger and larger pre-defined brackets (which
are simply lower-precision representations of the value).
The step size between each successive bracket is called the
<code>precisionStep</code>, measured in bits. Smaller
<code>precisionStep</code> values result in larger number
of brackets, which consumes more disk space in the index
but may result in faster range search performance. The
default value, 4, was selected for a reasonable tradeoff
of disk space consumption versus performance. You can
create a custom <a class="xref" href="Lucene.Net.Documents.FieldType.html">FieldType</a> and invoke the
<a class="xref" href="Lucene.Net.Documents.FieldType.html#Lucene_Net_Documents_FieldType_NumericPrecisionStep">NumericPrecisionStep</a> setter if you&apos;d
like to change the value. Note that you must also
specify a congruent value when creating
<a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a> or <a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>.
For low cardinality fields larger precision steps are good.
If the cardinality is &lt; 100, it is fair
to use <span class="xref">System.Int32.MaxValue</span>, which produces one
term per value.</p>
<p>For more information on the internals of numeric trie
indexing, including the <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html#Lucene_Net_Search_NumericRangeQuery_1_PrecisionStep">PrecisionStep</a> <a href="../search/NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>
configuration, see <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a>. The format of
indexed values is described in <a class="xref" href="Lucene.Net.Util.NumericUtils.html">NumericUtils</a>.</p>
<p>If you only need to sort by numeric value, and never
run range querying/filtering, you can index using a
<code>precisionStep</code> of <span class="xref">System.Int32.MaxValue</span>.
this will minimize disk space consumed. </p>
<p><p>More advanced users can instead use
<a class="xref" href="Lucene.Net.Analysis.NumericTokenStream.html">NumericTokenStream</a> directly,
when indexing numbers. this
class is a wrapper around this token stream type for
easier, more intuitive usage.</p>
<p>
NOTE: This was IntField in Lucene
</p>
@since 2.9</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Int64DocValuesField.html">Int64DocValuesField</a></h4>
<section><p>
Field that stores a per-document <span class="xref">System.Int64</span> value for scoring,
sorting or value retrieval. Here&apos;s an example usage:
<pre><code> document.Add(new Int64DocValuesField(name, 22L));</code></pre></p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
<p>
NOTE: This was LongDocValuesField in Lucene
</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a></h4>
<section><p>
Field that indexes <span class="xref">System.Int64</span> values
for efficient range filtering and sorting. Here&apos;s an example usage:
<pre><code>document.Add(new Int64Field(name, 6L, Field.Store.NO));</code></pre>
For optimal performance, re-use the <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a> and
<a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> instance for more than one document:
<pre><code> Int64Field field = new Int64Field(name, 0L, Field.Store.NO);
Document document = new Document();
document.Add(field);
for (all documents) {
...
field.SetInt64Value(value)
writer.AddDocument(document);
...
}</code></pre>
See also <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>, <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>,
<a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>.
</p>
<p>
Any type that can be converted to long can also be
indexed. For example, date/time values represented by a
<span class="xref">System.DateTime</span> can be translated into a long
value using the <span class="xref">System.DateTime.Ticks</span> property. If you
don&apos;t need millisecond precision, you can quantize the
value, either by dividing the result of
<span class="xref">System.DateTime.Ticks</span> or using the separate getters
(for year, month, etc.) to construct an <span class="xref">System.Int32</span> or
<span class="xref">System.Int64</span> value.</p>
<p>To perform range querying or filtering against a
<a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>, use <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a> or
<a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>. To sort according to a
<a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>, use the normal numeric sort types, eg
<a class="xref" href="Lucene.Net.Search.SortFieldType.html#Lucene_Net_Search_SortFieldType_INT64">INT64</a>. <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>
values can also be loaded directly from <a class="xref" href="Lucene.Net.Search.IFieldCache.html">IFieldCache</a>.</p>
<p>You may add the same field name as an <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a> to
the same document more than once. Range querying and
filtering will be the logical OR of all values; so a range query
will hit all documents that have at least one value in
the range. However sort behavior is not defined. If you need to sort,
you should separately index a single-valued <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>.</p>
<p>An <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a> will consume somewhat more disk space
in the index than an ordinary single-valued field.
However, for a typical index that includes substantial
textual content per document, this increase will likely
be in the noise. </p>
<p>Within Lucene, each numeric value is indexed as a
<em>trie</em> structure, where each term is logically
assigned to larger and larger pre-defined brackets (which
are simply lower-precision representations of the value).
The step size between each successive bracket is called the
<code>precisionStep</code>, measured in bits. Smaller
<code>precisionStep</code> values result in larger number
of brackets, which consumes more disk space in the index
but may result in faster range search performance. The
default value, 4, was selected for a reasonable tradeoff
of disk space consumption versus performance. You can
create a custom <a class="xref" href="Lucene.Net.Documents.FieldType.html">FieldType</a> and invoke the
<a class="xref" href="Lucene.Net.Documents.FieldType.html#Lucene_Net_Documents_FieldType_NumericPrecisionStep">NumericPrecisionStep</a> setter if you&apos;d
like to change the value. Note that you must also
specify a congruent value when creating
<a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a> or <a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>.
For low cardinality fields larger precision steps are good.
If the cardinality is &lt; 100, it is fair
to use <span class="xref">System.Int32.MaxValue</span>, which produces one
term per value.</p>
<p>For more information on the internals of numeric trie
indexing, including the <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html#Lucene_Net_Search_NumericRangeQuery_1_PrecisionStep">PrecisionStep</a> <a href="../search/NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>
configuration, see <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a>. The format of
indexed values is described in <a class="xref" href="Lucene.Net.Util.NumericUtils.html">NumericUtils</a>.</p>
<p>If you only need to sort by numeric value, and never
run range querying/filtering, you can index using a
<code>precisionStep</code> of <span class="xref">System.Int32.MaxValue</span>.
this will minimize disk space consumed. </p>
<p><p>More advanced users can instead use
<a class="xref" href="Lucene.Net.Analysis.NumericTokenStream.html">NumericTokenStream</a> directly,
when indexing numbers. this
class is a wrapper around this token stream type for
easier, more intuitive usage.</p>
<p>
NOTE: This was LongField in Lucene
</p>
@since 2.9</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.NumericDocValuesField.html">NumericDocValuesField</a></h4>
<section><p>Field that stores a per-document <span class="xref">System.Int64</span> value for scoring,
sorting or value retrieval. Here&apos;s an example usage:</p>
<pre><code> document.Add(new NumericDocValuesField(name, 22L));</code></pre>
<p>If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.PackedInt64DocValuesField.html">PackedInt64DocValuesField</a></h4>
<section><p>
Field that stores a per-document <span class="xref">System.Int64</span> value
for scoring, sorting or value retrieval. Here&apos;s an example usage:
<pre><code> document.Add(new PackedInt64DocValuesField(name, 22L));</code></pre>
</p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.
</p>
<p>
NOTE: This was PackedLongDocValuesField in Lucene
</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.SingleDocValuesField.html">SingleDocValuesField</a></h4>
<section><p>Syntactic sugar for encoding floats as <a class="xref" href="Lucene.Net.Index.NumericDocValues.html">NumericDocValues</a>
via <span class="xref">J2N.BitConversion.SingleToRawInt32Bits(System.Single)</span>.
<p>
Per-document floating point values can be retrieved via
<a class="xref" href="Lucene.Net.Search.IFieldCache.html#Lucene_Net_Search_IFieldCache_GetSingles_Lucene_Net_Index_AtomicReader_System_String_System_Boolean_">GetSingles(AtomicReader, String, Boolean)</a>.</p>
<p>
<strong>NOTE</strong>: In most all cases this will be rather inefficient,
requiring four bytes per document. Consider encoding floating
point values yourself with only as much precision as you require.
</p>
<p>
NOTE: This was FloatDocValuesField in Lucene
</p></p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a></h4>
<section><p>
Field that indexes <span class="xref">System.Single</span> values
for efficient range filtering and sorting. Here&apos;s an example usage:
<pre><code>document.Add(new SingleField(name, 6.0F, Field.Store.NO));</code></pre>
For optimal performance, re-use the <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a> and
<a class="xref" href="Lucene.Net.Documents.Document.html">Document</a> instance for more than one document:
<pre><code> FloatField field = new SingleField(name, 0.0F, Field.Store.NO);
Document document = new Document();
document.Add(field);
for (all documents)
{
...
field.SetSingleValue(value)
writer.AddDocument(document);
...
}</code></pre>
See also <a class="xref" href="Lucene.Net.Documents.Int32Field.html">Int32Field</a>, <a class="xref" href="Lucene.Net.Documents.Int64Field.html">Int64Field</a>,
<a class="xref" href="Lucene.Net.Documents.DoubleField.html">DoubleField</a>.</p>
<p>To perform range querying or filtering against a
<a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>, use <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a> or
<a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>. To sort according to a
<a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>, use the normal numeric sort types, eg
<a class="xref" href="Lucene.Net.Search.SortFieldType.html#Lucene_Net_Search_SortFieldType_SINGLE">SINGLE</a>. <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>
values can also be loaded directly from <a class="xref" href="Lucene.Net.Search.IFieldCache.html">IFieldCache</a>.</p>
<p>You may add the same field name as an <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a> to
the same document more than once. Range querying and
filtering will be the logical OR of all values; so a range query
will hit all documents that have at least one value in
the range. However sort behavior is not defined. If you need to sort,
you should separately index a single-valued <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a>.</p>
<p>A <a class="xref" href="Lucene.Net.Documents.SingleField.html">SingleField</a> will consume somewhat more disk space
in the index than an ordinary single-valued field.
However, for a typical index that includes substantial
textual content per document, this increase will likely
be in the noise. </p>
<p>Within Lucene, each numeric value is indexed as a
<em>trie</em> structure, where each term is logically
assigned to larger and larger pre-defined brackets (which
are simply lower-precision representations of the value).
The step size between each successive bracket is called the
<code>precisionStep</code>, measured in bits. Smaller
<code>precisionStep</code> values result in larger number
of brackets, which consumes more disk space in the index
but may result in faster range search performance. The
default value, 4, was selected for a reasonable tradeoff
of disk space consumption versus performance. You can
create a custom <a class="xref" href="Lucene.Net.Documents.FieldType.html">FieldType</a> and invoke the
<a class="xref" href="Lucene.Net.Documents.FieldType.html#Lucene_Net_Documents_FieldType_NumericPrecisionStep">NumericPrecisionStep</a> setter if you&apos;d
like to change the value. Note that you must also
specify a congruent value when creating
<a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a>
or <a class="xref" href="Lucene.Net.Search.NumericRangeFilter-1.html">NumericRangeFilter&lt;T&gt;</a>.
For low cardinality fields larger precision steps are good.
If the cardinality is &lt; 100, it is fair
to use <span class="xref">System.Int32.MaxValue</span>, which produces one
term per value.</p>
<p>For more information on the internals of numeric trie
indexing, including the <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html#Lucene_Net_Search_NumericRangeQuery_1_PrecisionStep">PrecisionStep</a> <a href="../search/NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>
configuration, see <a class="xref" href="Lucene.Net.Search.NumericRangeQuery-1.html">NumericRangeQuery&lt;T&gt;</a>. The format of
indexed values is described in <a class="xref" href="Lucene.Net.Util.NumericUtils.html">NumericUtils</a>.</p>
<p>If you only need to sort by numeric value, and never
run range querying/filtering, you can index using a
<code>precisionStep</code> of <span class="xref">System.Int32.MaxValue</span>.
this will minimize disk space consumed. </p>
<p><p>More advanced users can instead use
<a class="xref" href="Lucene.Net.Analysis.NumericTokenStream.html">NumericTokenStream</a>
directly, when indexing numbers. This
class is a wrapper around this token stream type for
easier, more intuitive usage.</p>
<p>
NOTE: This was FloatField in Lucene
</p>
@since 2.9</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.SortedBytesDocValuesField.html">SortedBytesDocValuesField</a></h4>
<section><p>
Field that stores
a per-document <a class="xref" href="Lucene.Net.Util.BytesRef.html">BytesRef</a> value, indexed for
sorting. Here&apos;s an example usage:
<pre><code> document.Add(new SortedBytesDocValuesField(name, new BytesRef(&quot;hello&quot;)));</code></pre>
</p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.
</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.SortedDocValuesField.html">SortedDocValuesField</a></h4>
<section><p>
Field that stores
a per-document <a class="xref" href="Lucene.Net.Util.BytesRef.html">BytesRef</a> value, indexed for
sorting. Here&apos;s an example usage:
<pre><code> document.Add(new SortedDocValuesField(name, new BytesRef(&quot;hello&quot;)));</code></pre></p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.SortedSetDocValuesField.html">SortedSetDocValuesField</a></h4>
<section><p>
Field that stores
a set of per-document <a class="xref" href="Lucene.Net.Util.BytesRef.html">BytesRef</a> values, indexed for
faceting,grouping,joining. Here&apos;s an example usage:
<pre><code> document.Add(new SortedSetDocValuesField(name, new BytesRef(&quot;hello&quot;)));
document.Add(new SortedSetDocValuesField(name, new BytesRef(&quot;world&quot;)));</code></pre>
</p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a></h4>
<section><p>A field whose value is stored so that
<a class="xref" href="Lucene.Net.Search.IndexSearcher.html#Lucene_Net_Search_IndexSearcher_Doc_System_Int32_">Doc(Int32)</a> and <a class="xref" href="Lucene.Net.Index.IndexReader.html#Lucene_Net_Index_IndexReader_Document_System_Int32_">Document(Int32)</a> will
return the field and its value.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.StraightBytesDocValuesField.html">StraightBytesDocValuesField</a></h4>
<section><p>
Field that stores
a per-document <a class="xref" href="Lucene.Net.Util.BytesRef.html">BytesRef</a> value. If values may be shared it&apos;s
better to use <a class="xref" href="Lucene.Net.Documents.SortedDocValuesField.html">SortedDocValuesField</a>. Here&apos;s an example usage:
<pre><code> document.Add(new StraightBytesDocValuesField(name, new BytesRef(&quot;hello&quot;)));</code></pre></p>
<p>
If you also need to store the value, you should add a
separate <a class="xref" href="Lucene.Net.Documents.StoredField.html">StoredField</a> instance.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.StringField.html">StringField</a></h4>
<section><p>A field that is indexed but not tokenized: the entire
<span class="xref">System.String</span> value is indexed as a single token. For example
this might be used for a &apos;country&apos; field or an &apos;id&apos;
field, or any field that you intend to use for sorting
or access through the field cache.</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.TextField.html">TextField</a></h4>
<section><p>A field that is indexed and tokenized, without term
vectors. For example this would be used on a &apos;body&apos;
field, that contains the bulk of a document&apos;s text.</p>
</section>
<h3 id="enums">Enums
</h3>
<h4><a class="xref" href="Lucene.Net.Documents.DateTools.Resolution.html">DateTools.Resolution</a></h4>
<section><p>Specifies the time granularity. </p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Index.html">Field.Index</a></h4>
<section><p>Specifies whether and how a field should be indexed. </p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.Store.html">Field.Store</a></h4>
<section><p>Specifies whether and how a field should be stored. </p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.Field.TermVector.html">Field.TermVector</a></h4>
<section><p>Specifies whether and how a field should have term vectors. </p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.NumericFieldType.html">NumericFieldType</a></h4>
<section><p>Data type of the numeric <a class="xref" href="Lucene.Net.Index.IIndexableField.html">IIndexableField</a> value</p>
</section>
<h4><a class="xref" href="Lucene.Net.Documents.NumericType.html">NumericType</a></h4>
<section><p>Data type of the numeric value
@since 3.2</p>
</section>
</article>
</div>
<div class="hidden-sm col-md-2" role="complementary">
<div class="sideaffix">
<div class="contribution">
<ul class="nav">
<li>
<a href="https://github.com/apache/lucenenet/blob/docs/4.8.0-beta00010/src/Lucene.Net/Document/package.md/#L2" class="contribution-link">Improve this Doc</a>
</li>
</ul>
</div>
<nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
<!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
</nav>
</div>
</div>
</div>
</div>
<footer>
<div class="grad-bottom"></div>
<div class="footer">
<div class="container">
<span class="pull-right">
<a href="#top">Back to top</a>
</span>
Copyright © 2020 Licensed to the Apache Software Foundation (ASF)
</div>
</div>
</footer>
</div>
<script type="text/javascript" src="https://lucenenet.apache.org/docs/4.8.0-beta00009/styles/docfx.vendor.js"></script>
<script type="text/javascript" src="https://lucenenet.apache.org/docs/4.8.0-beta00009/styles/docfx.js"></script>
<script type="text/javascript" src="https://lucenenet.apache.org/docs/4.8.0-beta00009/styles/main.js"></script>
</body>
</html>