From 70f15595701a7e7f2803aeb3626a23a6fd6c731d Mon Sep 17 00:00:00 2001 From: Shad Storhaug Date: Mon, 10 Jul 2017 11:50:42 +0700 Subject: [PATCH] lucene-cli: Added Markdown documentation, and extended help text for many commands. Fixed IndexSplitCommand because MultiPassIndexSplitter doesn't make number of segments an optional argument. --- .../Commands/Index/IndexFixCommandTest.cs | 4 +- .../Commands/Index/IndexSplitCommandTest.cs | 34 +++++ .../lucene-cli/Resources/Strings.Designer.cs | 130 ++++++++++++------ src/tools/lucene-cli/Resources/Strings.resx | 92 ++++++++----- .../lucene-cli/arguments/SegmentsArgument.cs | 2 +- .../index/index-check/IndexCheckCommand.cs | 1 + .../IndexCopySegmentsCommand.cs | 3 +- .../IndexExtractCfsCommand.cs | 1 + .../index-list-cfs/IndexListCfsCommand.cs | 1 + .../IndexListHighFreqTerms.cs | 2 +- .../IndexSegmentListCommand.cs | 1 + .../IndexListTaxonomyStatsCommand.cs | 1 + .../IndexListTermInfoCommand.cs | 1 + .../index/index-split/IndexSplitCommand.cs | 8 +- .../lock-stress-test/LockStressTestCommand.cs | 9 +- src/tools/lucene-cli/docs/analysis/index.md | 10 ++ .../docs/analysis/stempel-compile-stems.md | 37 +++++ .../docs/analysis/stempel-patch-stems.md | 34 +++++ .../docs/demo/associations-facets.md | 27 ++++ .../lucene-cli/docs/demo/distance-facets.md | 27 ++++ .../demo/expression-aggregation-facets.md | 27 ++++ src/tools/lucene-cli/docs/demo/index-files.md | 51 +++++++ src/tools/lucene-cli/docs/demo/index.md | 17 +++ .../docs/demo/multi-category-lists-facets.md | 28 ++++ .../lucene-cli/docs/demo/range-facets.md | 27 ++++ .../lucene-cli/docs/demo/search-files.md | 72 ++++++++++ .../lucene-cli/docs/demo/simple-facets.md | 27 ++++ .../docs/demo/simple-sorted-set-facets.md | 29 ++++ src/tools/lucene-cli/docs/index.md | 25 ++++ src/tools/lucene-cli/docs/index/check.md | 55 ++++++++ .../lucene-cli/docs/index/copy-segments.md | 40 ++++++ .../lucene-cli/docs/index/delete-segments.md | 35 +++++ .../lucene-cli/docs/index/extract-cfs.md | 42 ++++++ src/tools/lucene-cli/docs/index/fix.md | 54 ++++++++ src/tools/lucene-cli/docs/index/index.md | 23 ++++ src/tools/lucene-cli/docs/index/list-cfs.md | 36 +++++ .../docs/index/list-high-freq-terms.md | 49 +++++++ .../lucene-cli/docs/index/list-segments.md | 32 +++++ .../docs/index/list-taxonomy-stats.md | 38 +++++ .../lucene-cli/docs/index/list-term-info.md | 40 ++++++ src/tools/lucene-cli/docs/index/merge.md | 36 +++++ src/tools/lucene-cli/docs/index/split.md | 54 ++++++++ src/tools/lucene-cli/docs/index/upgrade.md | 52 +++++++ src/tools/lucene-cli/docs/lock/index.md | 10 ++ src/tools/lucene-cli/docs/lock/stress-test.md | 55 ++++++++ .../lucene-cli/docs/lock/verify-server.md | 35 +++++ 46 files changed, 1332 insertions(+), 82 deletions(-) create mode 100644 src/tools/lucene-cli/docs/analysis/index.md create mode 100644 src/tools/lucene-cli/docs/analysis/stempel-compile-stems.md create mode 100644 src/tools/lucene-cli/docs/analysis/stempel-patch-stems.md create mode 100644 src/tools/lucene-cli/docs/demo/associations-facets.md create mode 100644 src/tools/lucene-cli/docs/demo/distance-facets.md create mode 100644 src/tools/lucene-cli/docs/demo/expression-aggregation-facets.md create mode 100644 src/tools/lucene-cli/docs/demo/index-files.md create mode 100644 src/tools/lucene-cli/docs/demo/index.md create mode 100644 src/tools/lucene-cli/docs/demo/multi-category-lists-facets.md create mode 100644 src/tools/lucene-cli/docs/demo/range-facets.md create mode 100644 src/tools/lucene-cli/docs/demo/search-files.md create mode 100644 src/tools/lucene-cli/docs/demo/simple-facets.md create mode 100644 src/tools/lucene-cli/docs/demo/simple-sorted-set-facets.md create mode 100644 src/tools/lucene-cli/docs/index.md create mode 100644 src/tools/lucene-cli/docs/index/check.md create mode 100644 src/tools/lucene-cli/docs/index/copy-segments.md create mode 100644 src/tools/lucene-cli/docs/index/delete-segments.md create mode 100644 src/tools/lucene-cli/docs/index/extract-cfs.md create mode 100644 src/tools/lucene-cli/docs/index/fix.md create mode 100644 src/tools/lucene-cli/docs/index/index.md create mode 100644 src/tools/lucene-cli/docs/index/list-cfs.md create mode 100644 src/tools/lucene-cli/docs/index/list-high-freq-terms.md create mode 100644 src/tools/lucene-cli/docs/index/list-segments.md create mode 100644 src/tools/lucene-cli/docs/index/list-taxonomy-stats.md create mode 100644 src/tools/lucene-cli/docs/index/list-term-info.md create mode 100644 src/tools/lucene-cli/docs/index/merge.md create mode 100644 src/tools/lucene-cli/docs/index/split.md create mode 100644 src/tools/lucene-cli/docs/index/upgrade.md create mode 100644 src/tools/lucene-cli/docs/lock/index.md create mode 100644 src/tools/lucene-cli/docs/lock/stress-test.md create mode 100644 src/tools/lucene-cli/docs/lock/verify-server.md diff --git a/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexFixCommandTest.cs b/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexFixCommandTest.cs index 29a2b4c441..d153f2d20a 100644 --- a/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexFixCommandTest.cs +++ b/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexFixCommandTest.cs @@ -64,7 +64,7 @@ public override void TestAllValidCombinations() AssertCommandTranslation( string.Join(" ", requiredArg.Select(x => x.InputPattern).ToArray()), requiredArg.SelectMany(x => x.Output) - // Special case - the -fix option must be specified when --dry-run is not + // Special case: the -fix option must be specified when --dry-run is not .Concat(new string[] { "-fix" }).ToArray()); } @@ -74,7 +74,7 @@ public override void TestAllValidCombinations() { string command = string.Join(" ", requiredArg.Select(x => x.InputPattern).Union(optionalArg.Select(x => x.InputPattern).ToArray())); string[] expected = requiredArg.SelectMany(x => x.Output) - // Special case - the -fix option must be specified when --dry-run is not + // Special case: the -fix option must be specified when --dry-run is not .Concat(command.Contains("--dry-run") ? new string[0] : new string[] { "-fix" }) .Union(optionalArg.SelectMany(x => x.Output)).ToArray(); AssertCommandTranslation(command, expected); diff --git a/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexSplitCommandTest.cs b/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexSplitCommandTest.cs index c5a901747e..a6a1a956f4 100644 --- a/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexSplitCommandTest.cs +++ b/src/tools/Lucene.Net.Tests.Cli/Commands/Index/IndexSplitCommandTest.cs @@ -1,5 +1,6 @@ using NUnit.Framework; using System.Collections.Generic; +using System.Linq; namespace Lucene.Net.Cli.Commands { @@ -52,6 +53,39 @@ protected override IList GetRequiredArgs() }; } + [Test] + public override void TestAllValidCombinations() + { + var requiredArgs = GetRequiredArgs().ExpandArgs().RequiredParameters(); + var optionalArgs = GetOptionalArgs().ExpandArgs().OptionalParameters(); + + foreach (var requiredArg in requiredArgs) + { + AssertCommandTranslation( + string.Join(" ", requiredArg.Select(x => x.InputPattern).ToArray()), + requiredArg.SelectMany(x => x.Output) + // Special case: the -num option must be specified when -n is not + // because in MultiPassIndexSplitter it is not optional, so we are patching + // it in our command to make 2 the default. + .Concat(new string[] { "-num", "2" }).ToArray()); + } + + foreach (var requiredArg in requiredArgs) + { + foreach (var optionalArg in optionalArgs) + { + string command = string.Join(" ", requiredArg.Select(x => x.InputPattern).Union(optionalArg.Select(x => x.InputPattern).ToArray())); + string[] expected = requiredArg.SelectMany(x => x.Output) + // Special case: the -num option must be specified when -n is not + // because in MultiPassIndexSplitter it is not optional, so we are patching + // it in our command to make 2 the default. + .Concat(command.Contains("-n") ? new string[0] : new string[] { "-num", "2" }) + .Union(optionalArg.SelectMany(x => x.Output)).ToArray(); + AssertCommandTranslation(command, expected); + } + } + } + [Test] public virtual void TestNotEnoughArguments() { diff --git a/src/tools/lucene-cli/Resources/Strings.Designer.cs b/src/tools/lucene-cli/Resources/Strings.Designer.cs index cb790ae30a..5d1fa93635 100644 --- a/src/tools/lucene-cli/Resources/Strings.Designer.cs +++ b/src/tools/lucene-cli/Resources/Strings.Designer.cs @@ -87,7 +87,7 @@ public static string AnalysisStempelCompileStemsCommandStemmerTableFilesDescript } /// - /// Looks up a localized string similar to The encoding to use for the stemmer table files.. + /// Looks up a localized string similar to The encoding to use for the stemmer table files. If not supplied, defaults to UTF-8.. /// public static string AnalysisStempelCompileStemsCommandStemmerTableFilesEncodingDescription { get { @@ -123,7 +123,7 @@ public static string AnalysisStempelPatchStemsCommandStemmerTableFilesDescriptio } /// - /// Looks up a localized string similar to The encoding to use for the stemmer table files.. + /// Looks up a localized string similar to The encoding to use for the stemmer table files. If not supplied, defaults to UTF-8.. /// public static string AnalysisStempelPatchStemsCommandStemmerTableFilesEncodingDescription { get { @@ -374,6 +374,17 @@ public static string IndexCheckCommandDescription { } } + /// + /// Looks up a localized string similar to Basic tool to check the health of an index. + /// + ///As this tool checks every byte in the index, on a large index it can take quite a long time to run.. + /// + public static string IndexCheckCommandExtendedHelpText { + get { + return ResourceManager.GetString("IndexCheckCommandExtendedHelpText", resourceCulture); + } + } + /// /// Looks up a localized string similar to Only check the specified segment(s). This can be specified multiple times, to check more than one segment, eg --segment _2 --segment _a.. /// @@ -492,7 +503,7 @@ public static string IndexExtractCfsCommandCFSFileNameDescription { } /// - /// Looks up a localized string similar to Lists sub-files from a .cfs compound file.. + /// Looks up a localized string similar to Extracts sub-files from a .cfs compound file.. /// public static string IndexExtractCfsCommandDescription { get { @@ -501,7 +512,9 @@ public static string IndexExtractCfsCommandDescription { } /// - /// Looks up a localized string similar to The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc.. + /// Looks up a localized string similar to Extracts `.cfs` compound files (that were created using the CompoundFileDirectory from Lucene.Net.Misc) to the current working directory. + /// + ///In order to make the extracted version of the index work, you have to copy the segments file from the compound index into the directory where the extracted files are stored.. /// public static string IndexExtractCfsCommandExtendedHelpText { get { @@ -528,7 +541,11 @@ public static string IndexFixCommandDryRunDescription { } /// - /// Looks up a localized string similar to WARNING: This command should only be used on an emergency basis as it will cause documents (perhaps many) to be permanently removed from the index. Always make a backup copy of your index before running this! Do not run this tool on an index that is actively being written to. You have been warned!. + /// Looks up a localized string similar to Basic tool to check and fix the health of an index and write a new segments file that removes reference to problematic segments. + /// + ///As this tool checks every byte in the index, on a large index it can take quite a long time to run. + /// + ///WARNING: This command should only be used on an emergency basis as it will cause documents (perhaps many) to be permanently removed from the index. Always make a backup copy of your index before running this! Do not run this tool on an index that is actively being written to. [rest of string was truncated]";. /// public static string IndexFixCommandExtendedHelpText { get { @@ -546,7 +563,7 @@ public static string IndexListCfsCommandCFSFileNameDescription { } /// - /// Looks up a localized string similar to Extracts sub-files out of a .cfs compound file.. + /// Looks up a localized string similar to Lists sub-files out of a .cfs compound file.. /// public static string IndexListCfsCommandDescription { get { @@ -555,7 +572,7 @@ public static string IndexListCfsCommandDescription { } /// - /// Looks up a localized string similar to The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc.. + /// Looks up a localized string similar to Prints the filename and size of each file within a given `.cfs` compound file. The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc.. /// public static string IndexListCfsCommandExtendedHelpText { get { @@ -564,7 +581,7 @@ public static string IndexListCfsCommandExtendedHelpText { } /// - /// Looks up a localized string similar to Extracts the top n most frequent terms by document frequency.. + /// Looks up a localized string similar to Lists the top N most frequent terms by document frequency.. /// public static string IndexListHighFreqTermsCommandDescription { get { @@ -573,7 +590,7 @@ public static string IndexListHighFreqTermsCommandDescription { } /// - /// Looks up a localized string similar to Extracts the top n most frequent terms (by document frequency) from an index and reports thier document frequency.. + /// Looks up a localized string similar to Extracts the top N most frequent terms (by document frequency) from an index and reports thier document frequency.. /// public static string IndexListHighFreqTermsCommandExtendedHelpText { get { @@ -617,6 +634,15 @@ public static string IndexListSegmentsCommandDescription { } } + /// + /// Looks up a localized string similar to After running this command to view segments, use copy-segments to copy segments from one index directory to another or delete-segments to remove segments from an index.. + /// + public static string IndexListSegmentsExtendedHelpText { + get { + return ResourceManager.GetString("IndexListSegmentsExtendedHelpText", resourceCulture); + } + } + /// /// Looks up a localized string similar to Displays the taxonomy statistical information for a taxonomy index.. /// @@ -627,7 +653,16 @@ public static string IndexListTaxonomyStatsCommandDescription { } /// - /// Looks up a localized string similar to Recursively lists all descendent nodes.. + /// Looks up a localized string similar to Prints how many ords are under each dimension.. + /// + public static string IndexListTaxonomyStatsCommandExtendedHelpText { + get { + return ResourceManager.GetString("IndexListTaxonomyStatsCommandExtendedHelpText", resourceCulture); + } + } + + /// + /// Looks up a localized string similar to Recursively lists all descendant nodes.. /// public static string IndexListTaxonomyStatsCommandShowTreeDescription { get { @@ -699,7 +734,7 @@ public static string IndexMergeCommandInputDirectoryDescription { } /// - /// Looks up a localized string similar to Output directory to merge the indexes into.. + /// Looks up a localized string similar to The output directory to merge the input indexes into.. /// public static string IndexMergeCommandOutputDirectoryDescription { get { @@ -717,7 +752,20 @@ public static string IndexSplitCommandDescription { } /// - /// Looks up a localized string similar to Path to input index. Multiple values can be provided separated by a space.. + /// Looks up a localized string similar to Splits the input index into multiple equal parts. The method employed here uses IndexWriter.AddIndexes(IndexReader[]) where the input data comes from the input index with artificially applied deletes to the document ids that fall outside the selected partition. + /// + ///Deletes are only applied to a buffered list of deleted documents and don't affect the source index. This tool works also with read-only indexes. + /// + ///The disadvantage of this tool is that source index needs to be read as many times as there are part [rest of string was truncated]";. + /// + public static string IndexSplitCommandExtendedHelpText { + get { + return ResourceManager.GetString("IndexSplitCommandExtendedHelpText", resourceCulture); + } + } + + /// + /// Looks up a localized string similar to The path of the source index, which can have deletions and can have multiple segments (or multiple readers). Multiple values can be supplied separated by a space.. /// public static string IndexSplitCommandInputDirectoryDescription { get { @@ -726,7 +774,7 @@ public static string IndexSplitCommandInputDirectoryDescription { } /// - /// Looks up a localized string similar to The number of parts to produce.. + /// Looks up a localized string similar to The number of parts (output indices) to produce. If omitted, defaults to 2.. /// public static string IndexSplitCommandNumberOfPartsDescription { get { @@ -744,7 +792,7 @@ public static string IndexSplitCommandOutputDirectoryDescription { } /// - /// Looks up a localized string similar to Sequential docid-range split.. + /// Looks up a localized string similar to Sequential doc-id range split (default is round-robin).. /// public static string IndexSplitCommandSequentialDescription { get { @@ -771,7 +819,11 @@ public static string IndexUpgradeCommandDescription { } /// - /// Looks up a localized string similar to This tool keeps only the last commit in an index; for this reason, if the incoming index has more than one commit, the tool refuses to run by default. Specify --delete-prior-commits to override this, allowing the tool to delete all but the last commit. Specify an FSDirectory implementation through the --directory-type option to force its use. If not qualified by an AssemblyName, the Lucene.Net.dll assembly will be used. WARNING: This tool may reorder document IDs! Also, ensure you are using the correct vers [rest of string was truncated]";. + /// Looks up a localized string similar to This tool keeps only the last commit in an index; for this reason, if the incoming index has more than one commit, the tool refuses to run by default. Specify --delete-prior-commits to override this, allowing the tool to delete all but the last commit. + /// + ///Specify an FSDirectory implementation through the --directory-type option to force its use. If not qualified by an AssemblyName, the Lucene.Net.dll assembly will be used. + /// + ///WARNING: This tool may reorder document IDs! Be sure to make a backup of your in [rest of string was truncated]";. /// public static string IndexUpgradeCommandExtendedHelpText { get { @@ -789,16 +841,7 @@ public static string LockCommandDescription { } /// - /// Looks up a localized string similar to Number of locking tries.. - /// - public static string LockStressTestCommandCountDescription { - get { - return ResourceManager.GetString("LockStressTestCommandCountDescription", resourceCulture); - } - } - - /// - /// Looks up a localized string similar to Simple standalone tool that forever acquires & releases a lock using a specific LockFactory.. + /// Looks up a localized string similar to Simple tool that forever acquires and releases a lock using a specific LockFactory.. /// public static string LockStressTestCommandDescription { get { @@ -807,7 +850,7 @@ public static string LockStressTestCommandDescription { } /// - /// Looks up a localized string similar to You should run multiple instances of this process, each with its own unique ID, and each pointing to the same lock directory, to verify that locking is working correctly. Make sure you are first running LockVerifyServer.. + /// Looks up a localized string similar to You should run multiple instances of this process, each with its own unique ID, and each pointing to the same lock directory, to verify that locking is working correctly. Make sure you are first running verify-server.. /// public static string LockStressTestCommandExtendedHelpText { get { @@ -816,7 +859,7 @@ public static string LockStressTestCommandExtendedHelpText { } /// - /// Looks up a localized string similar to int value from 0 .. 255 (should be unique for test process).. + /// Looks up a localized string similar to An integer from 0 - 255 (should be unique for test process).. /// public static string LockStressTestCommandIDDescription { get { @@ -825,25 +868,25 @@ public static string LockStressTestCommandIDDescription { } /// - /// Looks up a localized string similar to Path to the lock directory (only set for Simple/NativeFSLockFactory).. + /// Looks up a localized string similar to The path to the lock directory (only utilized if LOCK_FACTORY_TYPE is set to SimpleFSLockFactory or NativeFSLockFactory).. /// - public static string LockStressTestCommandLockFactoryNameDescription { + public static string LockStressTestCommandLockDirectoryDescription { get { - return ResourceManager.GetString("LockStressTestCommandLockFactoryNameDescription", resourceCulture); + return ResourceManager.GetString("LockStressTestCommandLockDirectoryDescription", resourceCulture); } } /// - /// Looks up a localized string similar to Primary LockFactory class that we will use.. + /// Looks up a localized string similar to The primary LockFactory implementation that we will use.. /// - public static string LockStressTestCommandLockFactoryTypeNameDescription { + public static string LockStressTestCommandLockFactoryTypeDescription { get { - return ResourceManager.GetString("LockStressTestCommandLockFactoryTypeNameDescription", resourceCulture); + return ResourceManager.GetString("LockStressTestCommandLockFactoryTypeDescription", resourceCulture); } } /// - /// Looks up a localized string similar to Milliseconds to pause betweeen each lock obtain/release.. + /// Looks up a localized string similar to Milliseconds to pause between each lock obtain/release.. /// public static string LockStressTestCommandSleepTimeMSDescription { get { @@ -852,7 +895,16 @@ public static string LockStressTestCommandSleepTimeMSDescription { } /// - /// Looks up a localized string similar to Port that LockVerifyServer is listening on.. + /// Looks up a localized string similar to Number of locking tries.. + /// + public static string LockStressTestCommandTriesDescription { + get { + return ResourceManager.GetString("LockStressTestCommandTriesDescription", resourceCulture); + } + } + + /// + /// Looks up a localized string similar to Port that verify-server is listening on.. /// public static string LockStressTestCommandVerfierPortDescription { get { @@ -861,7 +913,7 @@ public static string LockStressTestCommandVerfierPortDescription { } /// - /// Looks up a localized string similar to Hostname that LockVerifyServer is listening on.. + /// Looks up a localized string similar to Hostname or IP address that verify-server is listening on.. /// public static string LockStressTestCommandVerifierHostDescription { get { @@ -870,7 +922,7 @@ public static string LockStressTestCommandVerifierHostDescription { } /// - /// Looks up a localized string similar to Simple standalone server that must be running when you use VerifyingLockFactory. This server verifies at most one process holds the lock at a time.. + /// Looks up a localized string similar to Simple server that must be running when you use VerifyingLockFactory (or stress-test). This server verifies at most one process holds the lock at a time.. /// public static string LockVerifyServerCommandDescription { get { @@ -879,7 +931,7 @@ public static string LockVerifyServerCommandDescription { } /// - /// Looks up a localized string similar to Hostname or IP address that LockVerifyServer will listen on.. + /// Looks up a localized string similar to Hostname or IP address that verify-server will listen on.. /// public static string LockVerifyServerCommandIPHostnameDescription { get { @@ -888,7 +940,7 @@ public static string LockVerifyServerCommandIPHostnameDescription { } /// - /// Looks up a localized string similar to The maximum number of concurrent clients.. + /// Looks up a localized string similar to The maximum number of connected clients.. /// public static string LockVerifyServerCommandMaxClientsDescription { get { diff --git a/src/tools/lucene-cli/Resources/Strings.resx b/src/tools/lucene-cli/Resources/Strings.resx index 2e4ce2a190..64be738f00 100644 --- a/src/tools/lucene-cli/Resources/Strings.resx +++ b/src/tools/lucene-cli/Resources/Strings.resx @@ -127,7 +127,7 @@ The path to a file containing a stemmer table. Multiple values are allowed. - The encoding to use for the stemmer table files. + The encoding to use for the stemmer table files. If not supplied, defaults to UTF-8. The name of the desired stemming algorithm to use. @@ -139,7 +139,7 @@ The path to a file containing a stemmer table. Multiple values are allowed. - The encoding to use for the stemmer table files. + The encoding to use for the stemmer table files. If not supplied, defaults to UTF-8. Cross check term vectors. @@ -222,6 +222,11 @@ Checks an index for problematic segments. + + Basic tool to check the health of an index. + +As this tool checks every byte in the index, on a large index it can take quite a long time to run. + Only check the specified segment(s). This can be specified multiple times, to check more than one segment, eg --segment _2 --segment _a. @@ -262,10 +267,12 @@ The .cfs compound file containing words to parse. - Lists sub-files from a .cfs compound file. + Extracts sub-files from a .cfs compound file. - The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc. + Extracts `.cfs` compound files (that were created using the CompoundFileDirectory from Lucene.Net.Misc) to the current working directory. + +In order to make the extracted version of the index work, you have to copy the segments file from the compound index into the directory where the extracted files are stored. Fixes an index by removing problematic segments. @@ -274,22 +281,26 @@ Doesn't change the index, but reports any actions that would be taken if this option were not supplied. - WARNING: This command should only be used on an emergency basis as it will cause documents (perhaps many) to be permanently removed from the index. Always make a backup copy of your index before running this! Do not run this tool on an index that is actively being written to. You have been warned! + Basic tool to check and fix the health of an index and write a new segments file that removes reference to problematic segments. + +As this tool checks every byte in the index, on a large index it can take quite a long time to run. + +WARNING: This command should only be used on an emergency basis as it will cause documents (perhaps many) to be permanently removed from the index. Always make a backup copy of your index before running this! Do not run this tool on an index that is actively being written to. You have been warned! The .cfs compound file containing words to parse. - Extracts sub-files out of a .cfs compound file. + Lists sub-files out of a .cfs compound file. - The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc. + Prints the filename and size of each file within a given `.cfs` compound file. The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc. - Extracts the top n most frequent terms by document frequency. + Lists the top N most frequent terms by document frequency. - Extracts the top n most frequent terms (by document frequency) from an index and reports thier document frequency. + Extracts the top N most frequent terms (by document frequency) from an index and reports thier document frequency. The field to consider. If omitted, considers all fields. @@ -303,11 +314,17 @@ Lists segments in an index. + + After running this command to view segments, use copy-segments to copy segments from one index directory to another or delete-segments to remove segments from an index. + Displays the taxonomy statistical information for a taxonomy index. + + Prints how many ords are under each dimension. + - Recursively lists all descendent nodes. + Recursively lists all descendant nodes. Gets document frequency and total number of occurrences of a term. @@ -331,22 +348,31 @@ Two or more source index directories separated by a space. - Output directory to merge the indexes into. + The output directory to merge the input indexes into. Splits an index into multiple parts. + + Splits the input index into multiple equal parts. The method employed here uses IndexWriter.AddIndexes(IndexReader[]) where the input data comes from the input index with artificially applied deletes to the document ids that fall outside the selected partition. + +Deletes are only applied to a buffered list of deleted documents and don't affect the source index. This tool works also with read-only indexes. + +The disadvantage of this tool is that source index needs to be read as many times as there are parts to be created. The multiple passes may be slow. + +NOTE: This tool is unaware of documents added automatically via IndexWriter.AddDocuments(IEnumerable<IEnumerable<IIndexableField>>, Analyzer) or IndexWriter.UpdateDocuments(Term, IEnumerable<IEnumerable<IIndexableField>>, Analyzer), which means it can easily break up such document groups. + - Path to input index. Multiple values can be provided separated by a space. + The path of the source index, which can have deletions and can have multiple segments (or multiple readers). Multiple values can be supplied separated by a space. - The number of parts to produce. + The number of parts (output indices) to produce. If omitted, defaults to 2. Path to output directory to contain partial indexes. - Sequential docid-range split. + Sequential doc-id range split (default is round-robin). Deletes prior commits. @@ -355,46 +381,50 @@ Upgrades all segments of an index from previous Lucene.Net versions to the current segment file format. - This tool keeps only the last commit in an index; for this reason, if the incoming index has more than one commit, the tool refuses to run by default. Specify --delete-prior-commits to override this, allowing the tool to delete all but the last commit. Specify an FSDirectory implementation through the --directory-type option to force its use. If not qualified by an AssemblyName, the Lucene.Net.dll assembly will be used. WARNING: This tool may reorder document IDs! Also, ensure you are using the correct version of this utility to match your application's version of Lucene.Net. + This tool keeps only the last commit in an index; for this reason, if the incoming index has more than one commit, the tool refuses to run by default. Specify --delete-prior-commits to override this, allowing the tool to delete all but the last commit. + +Specify an FSDirectory implementation through the --directory-type option to force its use. If not qualified by an AssemblyName, the Lucene.Net.dll assembly will be used. + +WARNING: This tool may reorder document IDs! Be sure to make a backup of your index before you use this. Also, ensure you are using the correct version of this utility to match your application's version of Lucene.Net. This operation cannot be reversed. Utilities for verifying concurrent locking integrity. - - Number of locking tries. - - Simple standalone tool that forever acquires & releases a lock using a specific LockFactory. + Simple tool that forever acquires and releases a lock using a specific LockFactory. - You should run multiple instances of this process, each with its own unique ID, and each pointing to the same lock directory, to verify that locking is working correctly. Make sure you are first running LockVerifyServer. + You should run multiple instances of this process, each with its own unique ID, and each pointing to the same lock directory, to verify that locking is working correctly. Make sure you are first running verify-server. - int value from 0 .. 255 (should be unique for test process). + An integer from 0 - 255 (should be unique for test process). - - Path to the lock directory (only set for Simple/NativeFSLockFactory). + + The path to the lock directory (only utilized if LOCK_FACTORY_TYPE is set to SimpleFSLockFactory or NativeFSLockFactory). - - Primary LockFactory class that we will use. + + The primary LockFactory implementation that we will use. - Milliseconds to pause betweeen each lock obtain/release. + Milliseconds to pause between each lock obtain/release. + + + Number of locking tries. - Port that LockVerifyServer is listening on. + Port that verify-server is listening on. - Hostname that LockVerifyServer is listening on. + Hostname or IP address that verify-server is listening on. - Simple standalone server that must be running when you use VerifyingLockFactory. This server verifies at most one process holds the lock at a time. + Simple server that must be running when you use VerifyingLockFactory (or stress-test). This server verifies at most one process holds the lock at a time. - Hostname or IP address that LockVerifyServer will listen on. + Hostname or IP address that verify-server will listen on. - The maximum number of concurrent clients. + The maximum number of connected clients. {0} arguments are required. diff --git a/src/tools/lucene-cli/arguments/SegmentsArgument.cs b/src/tools/lucene-cli/arguments/SegmentsArgument.cs index bf6b0c97fb..d7a406a726 100644 --- a/src/tools/lucene-cli/arguments/SegmentsArgument.cs +++ b/src/tools/lucene-cli/arguments/SegmentsArgument.cs @@ -23,7 +23,7 @@ public class SegmentsArgument : CommandArgument { public SegmentsArgument() { - Name = "[ []]"; + Name = "[ ...]"; Description = Resources.Strings.SegmentsArgumentDescription; MultipleValues = true; } diff --git a/src/tools/lucene-cli/commands/index/index-check/IndexCheckCommand.cs b/src/tools/lucene-cli/commands/index/index-check/IndexCheckCommand.cs index 11d9e9678c..5f216afc61 100644 --- a/src/tools/lucene-cli/commands/index/index-check/IndexCheckCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-check/IndexCheckCommand.cs @@ -37,6 +37,7 @@ public Configuration(CommandLineOptions options) this.Name = "check"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Arguments.Add(new IndexDirectoryArgument()); this.Options.Add(new VerboseOption()); diff --git a/src/tools/lucene-cli/commands/index/index-copy-segments/IndexCopySegmentsCommand.cs b/src/tools/lucene-cli/commands/index/index-copy-segments/IndexCopySegmentsCommand.cs index 47caa6361a..d5aa62bfcd 100644 --- a/src/tools/lucene-cli/commands/index/index-copy-segments/IndexCopySegmentsCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-copy-segments/IndexCopySegmentsCommand.cs @@ -29,13 +29,12 @@ public Configuration(CommandLineOptions options) this.Name = "copy-segments"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Argument("", FromResource("InputDirectoryDescription")); this.Argument("", FromResource("OutputDirectoryDescription")); this.Arguments.Add(new SegmentsArgument() { Description = FromResource("SegmentsDescription") }); - this.ExtendedHelpText = FromResource("ExtendedHelpText"); - this.OnExecute(() => new IndexCopySegmentsCommand().Run(this)); } } diff --git a/src/tools/lucene-cli/commands/index/index-extract-cfs/IndexExtractCfsCommand.cs b/src/tools/lucene-cli/commands/index/index-extract-cfs/IndexExtractCfsCommand.cs index 874f6a62bb..97f7b9929c 100644 --- a/src/tools/lucene-cli/commands/index/index-extract-cfs/IndexExtractCfsCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-extract-cfs/IndexExtractCfsCommand.cs @@ -30,6 +30,7 @@ public Configuration(CommandLineOptions options) this.Name = "extract-cfs"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Argument("", FromResource("CFSFileNameDescription")); this.Options.Add(new DirectoryTypeOption()); diff --git a/src/tools/lucene-cli/commands/index/index-list-cfs/IndexListCfsCommand.cs b/src/tools/lucene-cli/commands/index/index-list-cfs/IndexListCfsCommand.cs index 4b05cbb3c5..208464958b 100644 --- a/src/tools/lucene-cli/commands/index/index-list-cfs/IndexListCfsCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-list-cfs/IndexListCfsCommand.cs @@ -37,6 +37,7 @@ public Configuration(CommandLineOptions options) this.Name = "list-cfs"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Argument("", FromResource("CFSFileNameDescription")); this.Options.Add(new DirectoryTypeOption()); diff --git a/src/tools/lucene-cli/commands/index/index-list-high-freq-terms/IndexListHighFreqTerms.cs b/src/tools/lucene-cli/commands/index/index-list-high-freq-terms/IndexListHighFreqTerms.cs index ced2b9d522..c4367ea312 100644 --- a/src/tools/lucene-cli/commands/index/index-list-high-freq-terms/IndexListHighFreqTerms.cs +++ b/src/tools/lucene-cli/commands/index/index-list-high-freq-terms/IndexListHighFreqTerms.cs @@ -38,7 +38,7 @@ public Configuration(CommandLineOptions options) FromResource("TotalTermFrequencyDescription"), CommandOptionType.NoValue); this.NumberOfTermsOption = this.Option( - "-n|--number-of-terms ", + "-n|--number-of-terms ", FromResource("NumberOfTermsDescription"), CommandOptionType.SingleValue); this.FieldOption = this.Option( diff --git a/src/tools/lucene-cli/commands/index/index-list-segments/IndexSegmentListCommand.cs b/src/tools/lucene-cli/commands/index/index-list-segments/IndexSegmentListCommand.cs index ca4d2dca61..1e636b5c26 100644 --- a/src/tools/lucene-cli/commands/index/index-list-segments/IndexSegmentListCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-list-segments/IndexSegmentListCommand.cs @@ -30,6 +30,7 @@ public Configuration(CommandLineOptions options) this.Name = "list-segments"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Arguments.Add(new IndexDirectoryArgument()); diff --git a/src/tools/lucene-cli/commands/index/index-list-taxonomy-stats/IndexListTaxonomyStatsCommand.cs b/src/tools/lucene-cli/commands/index/index-list-taxonomy-stats/IndexListTaxonomyStatsCommand.cs index ad985d89df..ad4772cbea 100644 --- a/src/tools/lucene-cli/commands/index/index-list-taxonomy-stats/IndexListTaxonomyStatsCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-list-taxonomy-stats/IndexListTaxonomyStatsCommand.cs @@ -31,6 +31,7 @@ public Configuration(CommandLineOptions options) this.Name = "list-taxonomy-stats"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Arguments.Add(new IndexDirectoryArgument()); this.ShowTreeOption = this.Option("-tree|--show-tree", FromResource("ShowTreeDescription"), CommandOptionType.NoValue); diff --git a/src/tools/lucene-cli/commands/index/index-list-term-info/IndexListTermInfoCommand.cs b/src/tools/lucene-cli/commands/index/index-list-term-info/IndexListTermInfoCommand.cs index 780e8d16af..688372a6ae 100644 --- a/src/tools/lucene-cli/commands/index/index-list-term-info/IndexListTermInfoCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-list-term-info/IndexListTermInfoCommand.cs @@ -29,6 +29,7 @@ public Configuration(CommandLineOptions options) this.Name = "list-term-info"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Arguments.Add(new IndexDirectoryArgument(required: true) { Description = FromResource("IndexDirectoryDescription") }); this.Argument("", FromResource("FieldDescription")); diff --git a/src/tools/lucene-cli/commands/index/index-split/IndexSplitCommand.cs b/src/tools/lucene-cli/commands/index/index-split/IndexSplitCommand.cs index 80bd2eb2fd..b8cc60e297 100644 --- a/src/tools/lucene-cli/commands/index/index-split/IndexSplitCommand.cs +++ b/src/tools/lucene-cli/commands/index/index-split/IndexSplitCommand.cs @@ -60,11 +60,17 @@ public int Run(ConfigurationBase cmd) var input = cmd as Configuration; + args.Add("-num"); + if (input.NumberOfParts != null && input.NumberOfParts.HasValue()) { - args.Add("-num"); args.Add(input.NumberOfParts.Value()); } + else + { + // Default to 2 parts + args.Add("2"); + } if (input.Sequential != null && input.Sequential.HasValue()) { diff --git a/src/tools/lucene-cli/commands/lock/lock-stress-test/LockStressTestCommand.cs b/src/tools/lucene-cli/commands/lock/lock-stress-test/LockStressTestCommand.cs index 9b0f908baa..199ad08d6e 100644 --- a/src/tools/lucene-cli/commands/lock/lock-stress-test/LockStressTestCommand.cs +++ b/src/tools/lucene-cli/commands/lock/lock-stress-test/LockStressTestCommand.cs @@ -29,16 +29,15 @@ public Configuration(CommandLineOptions options) this.Name = "stress-test"; this.Description = FromResource("Description"); + this.ExtendedHelpText = FromResource("ExtendedHelpText"); this.Argument("", FromResource("IDDescription")); this.Argument("", FromResource("VerifierHostDescription")); this.Argument("", FromResource("VerfierPortDescription")); - this.Argument("", FromResource("LockFactoryTypeNameDescription")); - this.Argument("", FromResource("LockFactoryNameDescription")); + this.Argument("", FromResource("LockFactoryTypeDescription")); + this.Argument("", FromResource("LockDirectoryDescription")); this.Argument("", FromResource("SleepTimeMSDescription")); - this.Argument("", FromResource("CountDescription")); - - this.ExtendedHelpText = FromResource("ExtendedHelpText"); + this.Argument("", FromResource("TriesDescription")); this.OnExecute(() => new LockStressTestCommand().Run(this)); } diff --git a/src/tools/lucene-cli/docs/analysis/index.md b/src/tools/lucene-cli/docs/analysis/index.md new file mode 100644 index 0000000000..c114294e62 --- /dev/null +++ b/src/tools/lucene-cli/docs/analysis/index.md @@ -0,0 +1,10 @@ +# analysis + +## Description + +Utilities to manage specialized analyzers. + +## Commands + +- [stempel-compile-stems](stempel-compile-stems.md) +- [stempel-patch-stems](stempel-patch-stems.md) \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/analysis/stempel-compile-stems.md b/src/tools/lucene-cli/docs/analysis/stempel-compile-stems.md new file mode 100644 index 0000000000..6aae62c882 --- /dev/null +++ b/src/tools/lucene-cli/docs/analysis/stempel-compile-stems.md @@ -0,0 +1,37 @@ +# stempel-compile-stems + +### Name + +`analysis-stempel-compile-stems` - Compiles a stemmer table for the Egothor stemmer in the Lucene.Net.Analysis.Stempel project. + +### Synopsis + +dotnet lucene-cli.dll analysis stempel-compile-stems [-e|--encoding] [?|-h|--help] + +### Description + +See the [Egothor project documentation](http://egothor.sourceforge.net/) for more information. + +### Arguments + +`STEMMING_ALGORITHM` + +The name of the desired stemming algorithm to use. Possible values are `Multi` (which changes the stemmer to use the MultiTrie2 rather than a Trie class to store its data) or `0` which instructs the stemmer to store the original data. Any other supplied value will use the default algorithm. See the [Egothor project documentation](http://egothor.sourceforge.net/) for more information. + +`STEMMER_TABLE_FILE` + +The path to a file containing a stemmer table. Multiple values can be supplied separated by a space. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-e|--encoding ` + +The file encoding used by the stemmer files. If not supplied, the default value is `UTF-8`. Note this value can alternatively be supplied by setting the environment variable `egothor.stemmer.charset`. + +### Example + +dotnet lucene-cli.dll analysis stempel-compile-stems test X:\stemmer-data\table1.txt X:\stemmer-data\table2.txt diff --git a/src/tools/lucene-cli/docs/analysis/stempel-patch-stems.md b/src/tools/lucene-cli/docs/analysis/stempel-patch-stems.md new file mode 100644 index 0000000000..9b4ce4a4bc --- /dev/null +++ b/src/tools/lucene-cli/docs/analysis/stempel-patch-stems.md @@ -0,0 +1,34 @@ +# stempel-patch-stems + +### Name + +`analysis-stempel-patch-stems` - Generates patch commands from an already prepared stemmer table for the Egothor stemmer in the Lucene.Net.Analysis.Stempel project. + +### Synopsis + +dotnet lucene-cli.dll analysis stempel-patch-stems [-e|--encoding] [?|-h|--help] + +### Description + +See the [Egothor project documentation](http://egothor.sourceforge.net/) for more information. + +### Arguments + +`STEMMER_TABLE_FILE` + +The path to a file containing a stemmer table. Multiple values can be supplied separated by a space. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-e|--encoding ` + +The file encoding used by the stemmer files. If not supplied, the default value is `UTF-8`. Note this value can alternatively be supplied by setting the environment variable `egothor.stemmer.charset`. + +### Example + +dotnet lucene-cli.dll analysis stempel-patch-stems X:\stemmer-data\table1.txt X:\stemmer-data\table2.txt --encoding UTF-16 + diff --git a/src/tools/lucene-cli/docs/demo/associations-facets.md b/src/tools/lucene-cli/docs/demo/associations-facets.md new file mode 100644 index 0000000000..77b10fe8b4 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/associations-facets.md @@ -0,0 +1,27 @@ +# associations-facets + +### Name + +`demo-associations-facets` - Shows example usage of category associations. + +### Synopsis + +dotnet lucene-cli.dll demo associations-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +dotnet lucene-cli.dll demo associations-facets diff --git a/src/tools/lucene-cli/docs/demo/distance-facets.md b/src/tools/lucene-cli/docs/demo/distance-facets.md new file mode 100644 index 0000000000..abfdf3a907 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/distance-facets.md @@ -0,0 +1,27 @@ +# distance-facets + +### Name + +`demo-distance-facets` - Shows simple usage of dynamic range faceting, using the expressions module to calculate distance. + +### Synopsis + +dotnet lucene-cli.dll demo distance-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +dotnet lucene-cli.dll demo distance-facets diff --git a/src/tools/lucene-cli/docs/demo/expression-aggregation-facets.md b/src/tools/lucene-cli/docs/demo/expression-aggregation-facets.md new file mode 100644 index 0000000000..86339821d8 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/expression-aggregation-facets.md @@ -0,0 +1,27 @@ +# expression-aggregation-facets + +### Name + +`demo-expression-aggregation-facets` - Shows facets aggregation by an expression. + +### Synopsis + +dotnet lucene-cli.dll demo expression-aggregation-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +dotnet lucene-cli.dll demo expression-aggregation-facets diff --git a/src/tools/lucene-cli/docs/demo/index-files.md b/src/tools/lucene-cli/docs/demo/index-files.md new file mode 100644 index 0000000000..10d1806600 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/index-files.md @@ -0,0 +1,51 @@ +# index-files + +### Name + +`demo-index-files` - Index all files under a directory. + +### Synopsis + +``` +dotnet lucene-cli.dll demo index-files [-u|--update] [?|-h|--help] +dotnet lucene-cli.dll demo index-files [-src|--view-source-code] [-out|--output-source-code] +``` + +### Description + +This demo can be used to learn how to build a Lucene.Net index. After the index has been built, you can run the [search-files demo](search-files.md) to run queries against it. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. + +`SOURCE_DIRECTORY` + +The source directory containing the files to index. This directory will be analyzed recursively. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-u|--update` + +Adds new documents to an existing index. If not supplied, any existing index in the `INDEX_DIRECTORY` will be overwritten. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +Indexes the contents of `C:\Users\BGates\Documents\` and places the Lucene.Net index in `X:\test-index\`. + +dotnet lucene-cli.dll demo index-files X:\test-index C:\Users\BGates\Documents + diff --git a/src/tools/lucene-cli/docs/demo/index.md b/src/tools/lucene-cli/docs/demo/index.md new file mode 100644 index 0000000000..27f4ec1521 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/index.md @@ -0,0 +1,17 @@ +# demo + +## Description + +Demos for various Lucene.Net functionality including C# code samples. + +## Commands + +- [associations-facets](associations-facets.md) +- [distance-facets](distance-facets.md) +- [expression-aggregation-facets](expression-aggregation-facets.md) +- [index-files](index-files.md) +- [multi-category-lists-facets](multi-category-lists-facets.md) +- [range-facets](range-facets.md) +- [search-files](search-files.md) +- [simple-facets](simple-facets.md) +- [simple-sorted-set-facets](simple-sorted-set-facets.md) \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/demo/multi-category-lists-facets.md b/src/tools/lucene-cli/docs/demo/multi-category-lists-facets.md new file mode 100644 index 0000000000..f486c2a577 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/multi-category-lists-facets.md @@ -0,0 +1,28 @@ +# multi-category-lists-facets + +### Name + +`demo-multi-category-lists-facets` - Demonstrates indexing categories into different indexed fields. + +### Synopsis + +dotnet lucene-cli.dll demo multi-category-lists-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + + +### Example + +dotnet lucene-cli.dll demo multi-category-lists-facets diff --git a/src/tools/lucene-cli/docs/demo/range-facets.md b/src/tools/lucene-cli/docs/demo/range-facets.md new file mode 100644 index 0000000000..09e392ea77 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/range-facets.md @@ -0,0 +1,27 @@ +# range-facets + +### Name + +`demo-range-facets` - Shows simple usage of dynamic range faceting. + +### Synopsis + +dotnet lucene-cli.dll demo range-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +dotnet lucene-cli.dll demo range-facets \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/demo/search-files.md b/src/tools/lucene-cli/docs/demo/search-files.md new file mode 100644 index 0000000000..3bbfe38434 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/search-files.md @@ -0,0 +1,72 @@ +# search-files + +### Name + +`demo-search-files` - Simple command-line based search demo. + +### Synopsis + +``` +dotnet lucene-cli.dll demo search-files [-f|--field] [-r|--repeat] [-qf|--queries-file] [-q|--query] [--raw] [-p|--page-size] [?|-h|--help] +dotnet lucene-cli.dll demo search-files [-src|--view-source-code] [-out|--output-source-code] +``` + +### Description + +Run the [index-files demo](index-files.md) first to generate an index to search. + +> NOTE: To run queries interactively in the console, omit both the `--queries-file` and the `--query` arguments. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index that has previously been created using the [index-files demo](index-files.md). + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-f|--field ` + +The index field to use in the search. If not supplied, defaults to `contents`. + +`-r|--repeat ` + +Repeat the search and time as a benchmark. + +`-qf|--queries-file ` + +A file containing the queries to perform. + +`-q|--query ` + +A query to perform. + +`--raw` + +Output raw format. + +`-p|--page-size ` + +Hits per page to display. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Examples + +Search the index located in the `X:\test-index` directory interactively, showing 15 results per page in raw format: + +dotnet lucene-cli.dll demo search-files X:\test-index -p 15 --raw + +Run the query "foobar" against the "path" field in the index located in the `X:\test-index` directory: + +dotnet lucene-cli.dll demo search-files X:\test-index --field path --query foobar \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/demo/simple-facets.md b/src/tools/lucene-cli/docs/demo/simple-facets.md new file mode 100644 index 0000000000..cdb8f30119 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/simple-facets.md @@ -0,0 +1,27 @@ +# simple-facets + +### Name + +`demo-simple-facets` - Shows simple usage of faceted indexing and searching. + +### Synopsis + +dotnet lucene-cli.dll demo simple-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +dotnet lucene-cli.dll demo simple-facets \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/demo/simple-sorted-set-facets.md b/src/tools/lucene-cli/docs/demo/simple-sorted-set-facets.md new file mode 100644 index 0000000000..09052d9140 --- /dev/null +++ b/src/tools/lucene-cli/docs/demo/simple-sorted-set-facets.md @@ -0,0 +1,29 @@ +# simple-sorted-set-facets + +### Name + +`demo-simple-sorted-set-facets` - Shows simple usage of faceted indexing and search using SortedSetDocValuesFacetField and SortedSetDocValuesFacetCounts. + +### Synopsis + +dotnet lucene-cli.dll demo simple-sorted-set-facets [-src|--view-source-code] [-out|--output-source-code] [?|-h|--help] + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-src|--view-source-code` + +Prints the source code to the console. Use `SPACE` or `n` to move to the next page of text, `ENTER` to scroll to the next line of text, `q` or `x` to quit. + +`-out|--output-source-code ` + +Outputs the source code to the specified directory. + +### Example + +dotnet lucene-cli.dll demo simple-sorted-set-facets + + diff --git a/src/tools/lucene-cli/docs/index.md b/src/tools/lucene-cli/docs/index.md new file mode 100644 index 0000000000..933336f63c --- /dev/null +++ b/src/tools/lucene-cli/docs/index.md @@ -0,0 +1,25 @@ +# Lucene.Net command line interface (CLI) tools + +The Lucene.Net command line interface (CLI) is a new cross-platform toolchain with utilities for maintaining Lucene.Net and demos for learning basic Lucene.Net functionality. + +## Installation + +LUCENENET TODO + +## CLI Commands + +The following commands are installed: + +- [analysis](analysis/index.md) +- [demo](demo/index.md) +- [index](index/index.md) +- [lock](lock/index.md) + +## Command structure + +CLI command structure consists of the driver ("dotnet lucene-cli.dll"), the command, and possibly command arguments and options. You see this pattern in most CLI operations, such as checking a Lucene.Net index for problematic segments and fixing (removing) them: + +``` +dotnet lucene-cli.dll index check C:\my-index --verbose +dotnet lucene-cli.dll index fix C:\my-index +``` \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/index/check.md b/src/tools/lucene-cli/docs/index/check.md new file mode 100644 index 0000000000..caa18b2204 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/check.md @@ -0,0 +1,55 @@ +# check + +### Name + +`index-check` - Checks an index for problematic segments. + +### Synopsis + +dotnet lucene-cli.dll index check [] [-v|--verbose] [-c|--cross-check-term-vectors] [-dir|--directory-type] [-s|--segment] [?|-h|--help] + +### Description + +Basic tool to check the health of an index. + +As this tool checks every byte in the index, on a large index it can take quite a long time to run. + +### Arguments + +`INDEX_DIRECTORY` + +The path to the directory of the index to check. If omitted, it defaults to the current working directory. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-v|--verbose` + +Enable verbose output. + +`-c|--cross-check-term-vectors` + +Cross-check term vectors. + +`-dir|--directory-type ` + +The FSDirectory implementation to use. If ommitted, it defaults to the optimal FSDirectory for your OS platform. + +`-s|--segment ` + +Only check the specified segment(s). This can be specified multiple times, to check more than one segment, eg --segment _2 --segment _a. + +### Examples + +Check the index located at `X:\lucenenet-index\` verbosely, scanning only the segments named `_1j_Lucene41_0` and `_2u_Lucene41_0` for problems: + +dotnet lucene-cli.dll index check X:\lucenenet-index -v -s _1j_Lucene41_0 -s _2u_Lucene41_0 + + +Check the index located at `C:\taxonomy\` using the `MMapDirectory` memory-mapped directory implementation: + +dotnet lucene-cli.dll index check C:\taxonomy --directory-type MMapDirectory + diff --git a/src/tools/lucene-cli/docs/index/copy-segments.md b/src/tools/lucene-cli/docs/index/copy-segments.md new file mode 100644 index 0000000000..c9868efd4a --- /dev/null +++ b/src/tools/lucene-cli/docs/index/copy-segments.md @@ -0,0 +1,40 @@ +# copy-segments + +### Name + +`index-copy-segments` - Copies segments from one index to another index. + +### Synopsis + +dotnet lucene-cli.dll index copy-segments [ ...] [?|-h|--help] + +### Description + +This tool does file-level copying of segments files. This means it's unable to split apart a single segment into multiple segments. For example if your index is a single segment, this tool won't help. Also, it does basic file-level copying (using simple FileStream) so it will not work with non FSDirectory Directory implementations. + +### Arguments + +`INPUT_DIRECTORY` + +The directory of the index to copy. + +`OUTPUT_DIRECTORY` + +The directory of the destination index. + +`SEGMENT, SEGMENT_2` + +The segments to copy, separated by a space. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +Copy the `_71_Lucene41_0` segment from the index located at `X:\lucene-index` to the index located at `X:\output`: + +dotnet lucene-cli.dll index copy-segments X:\lucene-index X:\output _71_Lucene41_0 + diff --git a/src/tools/lucene-cli/docs/index/delete-segments.md b/src/tools/lucene-cli/docs/index/delete-segments.md new file mode 100644 index 0000000000..398d182f07 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/delete-segments.md @@ -0,0 +1,35 @@ +# delete-segments + +### Name + +`index-delete-segments` - Deletes segments from an index. + +### Synopsis + +dotnet lucene-cli.dll index delete-segments [ ...] [?|-h|--help] + +### Description + +You can easily accidentally remove segments from your index, so be careful! Always make a backup of your index first. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. + +`SEGMENT` + +The segments to delete, separated by a space. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +Delete the segments named `_8c` and `_83` from the index located at `X:\category-data\`: + +dotnet lucene-cli.dll index delete-segments X:\category-data _8c _83 diff --git a/src/tools/lucene-cli/docs/index/extract-cfs.md b/src/tools/lucene-cli/docs/index/extract-cfs.md new file mode 100644 index 0000000000..f6fc40e597 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/extract-cfs.md @@ -0,0 +1,42 @@ +# extract-cfs + +### Name + +`index-extract-cfs` - Extracts sub-files from a `.cfs` compound file. + +### Synopsis + +dotnet lucene-cli.dll index extract-cfs [-dir|--directory-type] [?|-h|--help] + +### Description + +Extracts `.cfs` compound files (that were created using the `CompoundFileDirectory` from Lucene.Net.Misc) to the current working directory. + +In order to make the extracted version of the index work, you have to copy the segments file from the compound index into the directory where the extracted files are stored. + +### Arguments + +`CFS_FILE_NAME` + +The path to a `.cfs` compound file containing words to parse. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-dir|--directory-type ` + +The FSDirectory implementation to use. If ommitted, it defaults to the optimal FSDirectory for your OS platform. + +### Examples + +Extract the files from the compound file at `X:\lucene-index\_81.cfs` to the current working directory: + +dotnet lucene-cli.dll index extract-cfs X:\lucene-index\_81.cfs + + +Extract the files from the compound file at `X:\lucene-index\_64.cfs` to the current working directory using the `SimpleFSDirectory` implementation: + +dotnet lucene-cli.dll index extract-cfs X:\lucene-index\_64.cfs --directory-type SimpleFSDirectory \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/index/fix.md b/src/tools/lucene-cli/docs/index/fix.md new file mode 100644 index 0000000000..3158aaba57 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/fix.md @@ -0,0 +1,54 @@ +# fix + +### Name + +`index-fix` - Fixes an index by removing problematic segments. + +### Synopsis + +dotnet lucene-cli.dll index fix [] [-v|--verbose] [-c|--cross-check-term-vectors] [-dir|--directory-type] [--dry-run] [?|-h|--help] + +### Description + +Basic tool to write a new segments file that removes reference to problematic segments. As this tool checks every byte in the index, on a large index it can take quite a long time to run. + +> **WARNING:** This command should only be used on an emergency basis as it will cause documents (perhaps many) to be permanently removed from the index. Always make a backup copy of your index before running this! Do not run this tool on an index that is actively being written to. You have been warned! + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. If omitted, it defaults to the current working directory. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-v|--verbose` + +Enables verbose output. + +`-c|--cross-check-term-vectors` + +Cross check term vectors. + +`-dir|--directory-type ` + +The `FSDirectory` implementation to use. If omitted, it defaults to the optimal `FSDirectory` for your OS platform. + +`--dry-run` + +Doesn't change the index, but reports any actions that would be taken if this option were not supplied. + +### Examples + +Check what a fix operation would do if run on the index located at `X:\product-index\`, using verbose output: + +dotnet lucene-cli.dll index fix X:\product-index --verbose --dry-run + + +Fix the index located at `X:\product-index` and cross check term vectors: + +dotnet lucene-cli.dll index fix X:\product-index -c \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/index/index.md b/src/tools/lucene-cli/docs/index/index.md new file mode 100644 index 0000000000..43f323e9d7 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/index.md @@ -0,0 +1,23 @@ +# index + +## Description + +Utilities to manage specialized analyzers. + +> **WARNING:** Many of these operations change an index in ways that cannot be reversed. Always make a backup of your index before running these commands. + +## Commands + +- [check](check.md) +- [copy-segments](copy-segments.md) +- [delete-segments](delete-segments.md) +- [extract-cfs](extract-cfs.md) +- [fix](fix.md) +- [list-cfs](list-cfs.md) +- [list-high-freq-terms](list-high-freq-terms.md) +- [list-segments](list-segments.md) +- [list-taxonomy-stats](list-taxonomy-stats.md) +- [list-term-info](list-term-info.md) +- [merge](merge.md) +- [split](split.md) +- [upgrade](upgrade.md) \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/index/list-cfs.md b/src/tools/lucene-cli/docs/index/list-cfs.md new file mode 100644 index 0000000000..6629dfa6d3 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/list-cfs.md @@ -0,0 +1,36 @@ +# list-cfs + +### Name + +`index-list-cfs` - Lists sub-files from a `.cfs` compound file. + +### Synopsis + +dotnet lucene-cli.dll index list-cfs [-dir|--directory-type] [?|-h|--help] + +### Description + +Prints the filename and size of each file within a given `.cfs` compound file. The .cfs compound file format is created using the CompoundFileDirectory from Lucene.Net.Misc. + +### Arguments + +`CFS_FILE_NAME` + +The `.cfs` compound file containing words to parse. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-dir|--directory-type ` + +The `FSDirectory` implementation to use. If omitted, defaults to the optimal `FSDirectory` for your OS platform. + +### Example + +Lists the files within the `X:\categories\_53.cfs` compound file using the `NIOFSDirectory` directory implementation: + +dotnet lucene-cli.dll index list-cfs X:\categories\_53.cfs -dir NIOFSDirectory + diff --git a/src/tools/lucene-cli/docs/index/list-high-freq-terms.md b/src/tools/lucene-cli/docs/index/list-high-freq-terms.md new file mode 100644 index 0000000000..bbeb364d17 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/list-high-freq-terms.md @@ -0,0 +1,49 @@ +# list-high-freq-terms + +### Name + +`index-list-high-freq-terms` - Lists the top *N* most frequent terms by document frequency. + +### Synopsis + +dotnet lucene-cli.dll index list-high-freq-terms [] [-t|--total-term-frequency] [-n|--number-of-terms] [-f|--field] [?|-h|--help] + +### Description + +Extracts the top *N* most frequent terms (by document frequency) from an existing Lucene index and reports their +document frequency. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. If omitted, it defaults to the current working directory. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-t|--total-term-frequency` + +Specifies that both the document frequency and term frequency are reported, ordered by descending total term frequency. + +`-n|--number-of-terms ` + +The number of terms to consider. If omitted, defaults to 100. + +`-f|--field ` + +The field to consider. If omitted, considers all fields. + +### Examples + +List the high frequency terms in the index located at `F:\product-index\` on the `description` field, reporting both document frequency and term frequency: + +dotnet lucene-cli.dll index list-high-freq-terms F:\product-index --total-term-frequency --field description + + +List the high frequency terms in the index located at `C:\lucene-index\` on the `name` field, tracking 30 terms: + +dotnet lucene-cli.dll index list-high-freq-terms C:\lucene-index --f name -n 30 diff --git a/src/tools/lucene-cli/docs/index/list-segments.md b/src/tools/lucene-cli/docs/index/list-segments.md new file mode 100644 index 0000000000..25f07b9d1c --- /dev/null +++ b/src/tools/lucene-cli/docs/index/list-segments.md @@ -0,0 +1,32 @@ +# list-segments + +### Name + +`index-list-segments` - Lists segments in an index. + +### Synopsis + +dotnet lucene-cli.dll index list-segments [] [?|-h|--help] + +### Description + +After running this command to view segments, use [copy-segments](copy-segments.md) to copy segments from one index directory to another or [delete-segments](delete-segments.md) to remove segments from an index. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. If omitted, it defaults to the current working directory. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +List the segments in the index located at `X:\lucene-index\`: + +dotnet lucene-cli.dll index list-segments X:\lucene-index + diff --git a/src/tools/lucene-cli/docs/index/list-taxonomy-stats.md b/src/tools/lucene-cli/docs/index/list-taxonomy-stats.md new file mode 100644 index 0000000000..7c43343bfc --- /dev/null +++ b/src/tools/lucene-cli/docs/index/list-taxonomy-stats.md @@ -0,0 +1,38 @@ +# list-taxonomy-stats + +### Name + +`index-list-taxonomy-stats` - Displays the taxonomy statistical information for a taxonomy index. + +### Synopsis + +dotnet lucene-cli.dll index list-taxonomy-stats [] [-tree|--show-tree] [?|-h|--help] + +### Description + +Prints how many ords are under each dimension. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. If omitted, it defaults to the current working directory. + +> **NOTE:** This directory must be a facet taxonomy directory for the command to succeed. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-tree|--show-tree` + +Recursively lists all descendant nodes. + +### Example + +List the taxonomy statistics from the index located at `X:\category-taxonomy-index\`, viewing all descendant nodes: + +dotnet lucene-cli.dll index list-taxonomy-stats X:\category-taxonomy-index -tree + diff --git a/src/tools/lucene-cli/docs/index/list-term-info.md b/src/tools/lucene-cli/docs/index/list-term-info.md new file mode 100644 index 0000000000..61b97e2733 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/list-term-info.md @@ -0,0 +1,40 @@ +# list-term-info + +### Name + +`index-list-term-info` - Gets document frequency and total number of occurrences of a term. + +### Synopsis + +dotnet lucene-cli.dll index list-term-info [?|-h|--help] + +### Description + +Gets document frequency and total number of occurrences (sum of the term frequency for each document) of a term. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. + +`FIELD` + +The field to consider. + +`TERM` + +The term to consider. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +List the term information from the index located at `C:\project-index\`: + +dotnet lucene-cli.dll index list-term-info C:\project-index + diff --git a/src/tools/lucene-cli/docs/index/merge.md b/src/tools/lucene-cli/docs/index/merge.md new file mode 100644 index 0000000000..98d296fab3 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/merge.md @@ -0,0 +1,36 @@ +# merge + +### Name + +`index-merge` - Merges multiple indexes into a single index. + +### Synopsis + +dotnet lucene-cli.dll index merge [ ...] [?|-h|--help] + +### Description + +Merges the the input index directories into a combined index at the output directory path. + +### Arguments + +`OUTPUT_DIRECTORY` + +The output directory to merge the input indexes into. + +`INPUT_DIRECTORY, INPUT_DIRECTORY_2, INPUT_DIRECTORY_N` + +Two or more input index directories, separated by a space. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +Merge the indexes `C:\product-index1` and `C:\product-index2` into an index located at `X:\merged-index`: + +dotnet lucene-cli.dll index merge X:\merged-index C:\product-index1 C:\product-index2 + diff --git a/src/tools/lucene-cli/docs/index/split.md b/src/tools/lucene-cli/docs/index/split.md new file mode 100644 index 0000000000..f2343d5708 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/split.md @@ -0,0 +1,54 @@ +# split + +### Name + +`index-split` - Splits an index into multiple equal parts. + +### Synopsis + +dotnet lucene-cli.dll index split [ ...] [-n|--number-of-parts] [-s|--sequential] [?|-h|--help] + +### Description + +Splits the input index into multiple equal parts. The method employed here uses `IndexWriter.AddIndexes(IndexReader[])` where the input data comes from the input index with artificially applied deletes to the document ids that fall outside the selected partition. + +Deletes are only applied to a buffered list of deleted documents and don't affect the source index. This tool works also with read-only indexes. + +The disadvantage of this tool is that source index needs to be read as many times as there are parts to be created. The multiple passes may be slow. + +> **NOTE:** This tool is unaware of documents added automatically via `IndexWriter.AddDocuments(IEnumerable<IEnumerable<IIndexableField>>, Analyzer)` or `IndexWriter.UpdateDocuments(Term, IEnumerable<IEnumerable<IIndexableField>>, Analyzer)`, which means it can easily break up such document groups. + +### Arguments + +`OUTPUT_DIRECTORY` + +Path to output directory to contain partial indexes. + +`INPUT_DIRECTORY, INPUT_DIRECTORY_2` + +The path of the source index, which can have deletions and can have multiple segments (or multiple readers). Multiple values can be supplied separated by a space. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-n|--number-of-parts ` + +The number of parts (output indices) to produce. If omitted, defaults to 2. + +`-s|--sequential` + +Sequential doc-id range split (default is round-robin). + +### Example + +Split the index located at `X:\old-index\` sequentially, placing the resulting 2 indices into the `X:\new-index\` directory: + +dotnet lucene-cli.dll index split X:\new-index X:\old-index --sequential + + +Split the index located at `T:\in\` into 4 parts and place them into the `T:\out\` directory: + +dotnet lucene-cli.dll index split T:\out T:\in -n 4 \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/index/upgrade.md b/src/tools/lucene-cli/docs/index/upgrade.md new file mode 100644 index 0000000000..20f5861c25 --- /dev/null +++ b/src/tools/lucene-cli/docs/index/upgrade.md @@ -0,0 +1,52 @@ +# upgrade + +### Name + +`index-upgrade` - Upgrades all segments of an index from previous Lucene.Net versions to the current segment file format. + +### Synopsis + +dotnet lucene-cli.dll index upgrade [] [-d|--delete-prior-commits] [-v|--verbose] [-dir|--directory-type] [?|-h|--help] + +### Description + +This tool keeps only the last commit in an index; for this reason, if the incoming index has more than one commit, the tool refuses to run by default. Specify --delete-prior-commits to override this, allowing the tool to delete all but the last commit. + +Specify an FSDirectory implementation through the --directory-type option to force its use. If not qualified by an AssemblyName, the Lucene.Net.dll assembly will be used. + +> **WARNING:** This tool may reorder document IDs! Be sure to make a backup of your index before you use this. Also, ensure you are using the correct version of this utility to match your application's version of Lucene.Net. This operation cannot be reversed. + +### Arguments + +`INDEX_DIRECTORY` + +The directory of the index. If omitted, it defaults to the current working directory. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +`-d|--delete-prior-commits` + +Deletes prior commits. + +`-v|--verbose` + +Verbose output. + +`-dir|--directory-type ` + +The `FSDirectory` implementation to use. Defaults to the optional `FSDirectory` for your OS platform. + +### Examples + +Upgrade the index format of the index located at `X:\lucene-index\` to the same version as this tool, using the `SimpleFSDirectory` implementation: + +dotnet lucene-cli.dll index upgrade X:\lucene-index -dir SimpleFSDirectory + + +Upgrade the index located at `C:\indexes\category-index\` verbosely, deleting all but the last commit: + +dotnet lucene-cli.dll index upgrade C:\indexes\category-index --verbose --delete-prior-commits diff --git a/src/tools/lucene-cli/docs/lock/index.md b/src/tools/lucene-cli/docs/lock/index.md new file mode 100644 index 0000000000..f0933770cb --- /dev/null +++ b/src/tools/lucene-cli/docs/lock/index.md @@ -0,0 +1,10 @@ +# lock + +## Description + +Utilities for verifying concurrent locking integrity. + +## Commands + +- [stress-test](stress-test.md) +- [verify-server](verify-server.md) \ No newline at end of file diff --git a/src/tools/lucene-cli/docs/lock/stress-test.md b/src/tools/lucene-cli/docs/lock/stress-test.md new file mode 100644 index 0000000000..b1d49a5896 --- /dev/null +++ b/src/tools/lucene-cli/docs/lock/stress-test.md @@ -0,0 +1,55 @@ +# stress-test + +### Name + +`lock-stress-test` - Simple tool that forever acquires and releases a lock using a specific `LockFactory`. + +### Synopsis + +dotnet lucene-cli.dll lock stress-test [?|-h|--help] + +### Description + +You should run multiple instances of this process, each with its own unique ID, and each pointing to the same lock directory, to verify that locking is working correctly. Make sure you are first running [verify-server](verify-server.md). + +### Arguments + +`ID` + +An integer from 0 - 255 (should be unique for test process). + +`VERIFIER_HOST` + +Hostname or IP address that [verify-server](verify-server.md) is listening on. + +`VERIFIER_PORT` + +Port that [verify-server](verify-server.md) is listening on. + +`LOCK_FACTORY_TYPE` + +The primary LockFactory implementation that we will use. + +`LOCK_DIRECTORY` + +The path to the lock directory (only utilized if `LOCK_FACTORY_TYPE` is set to `SimpleFSLockFactory` or `NativeFSLockFactory`). + +`SLEEP_TIME_MS` + +Milliseconds to pause between each lock obtain/release. + +`TRIES` + +Number of locking tries. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +Run the client (stress test), connecting to the server on IP address `127.0.0.4` and port `54464` using the ID 3, the `NativeFSLockFactory`, specifying the lock directory as `F:\temp`, sleep for 50 milliseconds, and try to obtain a lock up to 10 times: + +dotnet lucene-cli.dll lock stress-test 3 127.0.0.4 54464 NativeFSLockFactory F:\temp 50 10 diff --git a/src/tools/lucene-cli/docs/lock/verify-server.md b/src/tools/lucene-cli/docs/lock/verify-server.md new file mode 100644 index 0000000000..a34dce12a2 --- /dev/null +++ b/src/tools/lucene-cli/docs/lock/verify-server.md @@ -0,0 +1,35 @@ +# verify-server + +### Name + +`lock-verify-server` - Server that must be running when you use VerifyingLockFactory (or [stress-test](stress-test.md)). + +### Synopsis + +dotnet lucene-cli.dll lock verify-server [?|-h|--help] + +### Description + +This server simply verifies that at most one process holds the lock at a time. + +### Arguments + +`IP_HOSTNAME` + +Hostname or IP address that [verify-server](verify-server.md) will listen on. + +`MAX_CLIENTS` + +The maximum number of connected clients. + +### Options + +`?|-h|--help` + +Prints out a short help for the command. + +### Example + +Run the server on IP `127.0.0.4` with a maximum of 100 connected clients allowed: + +dotnet lucene-cli.dll lock verify-server 127.0.0.4 100