대용량 파일 저장

이 페이지의 내용

개요

GridFS 작동 방식
GridFS 버킷 만들기
버킷 사용자 지정
파일 업로드
업로드 스트림에 쓰기
기존 스트림 업로드
파일 다운로드
다운로드 스트림에서 읽기
기존 스트림에 다운로드
파일 찾기
파일 삭제
API 문서

개요

이 가이드 에서는 GridFS 를 사용하여 MongoDB 에 대용량 파일을 저장 하고 조회 하는 방법을 학습 수 있습니다. GridFS 저장 시스템은 파일을 저장할 때 청크로 분할하고 검색할 때 해당 파일을 재조립합니다. 드라이버의 GridFS 구현 은 파일 저장 의 운영 및 조직 을 관리하는 추상화입니다.

파일 크기가 BSON 문서 크기 제한인 16 MB를 초과하는 경우 GridFS 를 사용하세요. GridFS 가 사용 사례 에 적합한지 여부에 대한 자세한 내용은 MongoDB Server 매뉴얼에서GridFS 를 참조하세요.

GridFS 작동 방식

GridFS는 파일 청크와 파일을 설명하는 정보가 들어 있는 MongoDB 컬렉션 그룹인 버킷에 파일을 구성합니다. 버킷에는 다음과 같은 컬렉션이 포함되어 있습니다.

chunks: 바이너리 파일 청크를 저장합니다.
files: 파일 메타데이터 를 저장합니다.

운전자 는 GridFS 버킷에 처음 데이터를 쓰기 (write) 때 GridFS 버킷이 아직 존재하지 않는 경우 이를 생성합니다. 버킷에는 다른 이름을 지정하지 않는 한 기본값 버킷 이름 fs 접두사가 붙은 chunks 및 files 컬렉션이 포함되어 있습니다. 파일 및 관련 메타데이터 를 효율적으로 검색하기 위해 운전자 는 각 컬렉션 에 인덱스 를 생성합니다. 운전자 는 GridFS 버킷에서 읽기 및 쓰기 (write) 작업을 수행하기 전에 이러한 인덱스가 존재하는지 확인합니다.

GridFS 인덱스에 대한 자세한 내용은 MongoDB Server 매뉴얼에서 GridFS 인덱스를 참조하세요.

GridFS 를 사용하여 파일을 저장 때 운전자 는 파일을 작은 청크로 분할하며, 각 청크는 chunks 컬렉션 에서 별도의 문서 로 표시됩니다. 또한 files 컬렉션 에 파일 ID, 파일 이름 및 기타 파일 메타데이터 가 포함된 문서 를 만듭니다.

다음 다이어그램은 파일이 버킷에 업로드될 때 GridFS 가 파일을 분할하는 방법을 보여줍니다.

GridFS가 파일을 버킷에 업로드하는 방법을 보여주는 다이어그램입니다.

파일을 검색할 때 GridFS는 지정된 버킷의 files 컬렉션에서 메타데이터를 가져와서 이 정보를 사용하여 chunks 컬렉션의 문서에서 파일을 재구성합니다.

GridFS 버킷 만들기

GridFS 를 사용하여 파일을 저장 하거나 조회 하려면 GridFSBucket 클래스의 새 인스턴스 를 만들고 데이터베이스 를 나타내는 IMongoDatabase 객체 를 전달합니다. 이 메서드는 기존 버킷에 액세스하거나 버킷이 없는 경우 새 버킷을 생성합니다.

다음 예시 에서는 db 데이터베이스 에 대한 GridFSBucket 클래스의 새 인스턴스 를 만듭니다.

var client = new MongoClient("<connection string>");
var database = client.GetDatabase("db");
// Creates a GridFS bucket or references an existing one
var bucket = new GridFSBucket(database);

버킷 사용자 지정

GridFSBucketOptions 클래스의 인스턴스 를 GridFSBucket() 생성자에 전달하여 GridFS 버킷 구성을 사용자 지정할 수 있습니다. 다음 표에서는 GridFSBucketOptions 클래스의 속성에 대해 설명합니다.

필드	설명
`BucketName`	파일 및 청크 컬렉션의 접두사로 사용할 버킷 이름입니다. 기본값 은 `"fs"` 입니다. 데이터 유형: `string`
`ChunkSizeBytes`	GridFS 가 파일을 분할하는 청크 크기입니다. 기본값 은 255 KB입니다. 데이터 유형: `integer`
`ReadConcern`	버킷 작업에 사용할 읽기 고려 (read concern) 입니다. 기본값 은 데이터베이스의 읽기 고려 (read concern) 입니다. 데이터 유형: ReadConcern
`ReadPreference`	버킷 작업에 사용할 읽기 설정 (read preference) 입니다. 기본값 은 데이터베이스의 읽기 설정 (read preference) 입니다. 데이터 유형: ReadPreference
`WriteConcern`	버킷 작업에 사용할 쓰기 고려 (write concern) 입니다. 기본값 은 데이터베이스의 쓰기 고려 (write concern) 입니다. 데이터 유형: 쓰기 고려

다음 예시 에서는 GridFSBucketOptions 클래스의 인스턴스 를 GridFSBucket() 생성자에 전달하여 이름이 "myCustomBucket" 인 버킷을 만듭니다.

var options = new GridFSBucketOptions { BucketName = "myCustomBucket" };
var customBucket = new GridFSBucket(database, options);

파일 업로드

다음 방법을 사용하여 GridFS 버킷에 파일을 업로드할 수 있습니다.

OpenUploadStream() 또는 OpenUploadStreamAsync(): 파일 콘텐츠를 쓰기 (write) 수 있는 새 업로드 스트림 을 엽니다.
UploadFromStream() 또는 UploadFromStreamAsync(): 기존 스트림 의 콘텐츠를 GridFS 파일 에 업로드합니다.

다음 섹션에서는 이러한 메서드를 사용하는 방법에 대해 설명합니다.

업로드 스트림에 쓰기

OpenUploadStream() 또는 OpenUploadStreamAsync() 메서드를 사용하여 지정된 파일 이름에 대한 업로드 스트림 을 만듭니다. 이러한 메서드는 다음 매개변수를 허용합니다.

Parameter	설명
`filename`	업로드할 파일 의 이름입니다. 데이터 유형: `string`
`options`	선택사항. 업로드 스트림 의 구성을 지정하는 클래스의 인스턴스 입니다. 기본값 은 `GridFSUploadOptions` `null` 입니다. 데이터 유형: GridFSUploadOptions
`cancellationToken`	선택 사항. 작업을 취소하는 데 사용할 수 있는 토큰입니다. 데이터 유형: CancellationToken

이 코드 예시 에서는 다음 단계를 수행하여 업로드 스트림 을 여는 방법을 보여 줍니다.

OpenUploadStream() 메서드를 호출하여 "my_file"이라는 파일 에 대해 쓰기 가능한 GridFS 스트림 을 엽니다.
Write() 메서드를 호출하여 my_file에 데이터를 쓰기 (write) .
Close() 메서드를 호출하여 my_file을(를) 가리키는 스트림 을 닫습니다.

Synchronous 또는 Asynchronous 탭 을 선택하여 해당 코드를 확인합니다.

using (var uploader = bucket.OpenUploadStream("my_file"))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    uploader.Write(bytes, 0, bytes.Length);
    uploader.Close();
}

using (var uploader = await bucket.OpenUploadStreamAsync("my_file", options))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    await uploader.WriteAsync(bytes, 0, bytes.Length);
    await uploader.CloseAsync();
}

업로드 스트림 구성을 사용자 지정하려면 GridFSUploadOptions 클래스의 인스턴스 를 OpenUploadStream() 또는 OpenUploadStreamAsync() 메서드에 전달합니다. GridFSUploadOptions 클래스에는 다음과 같은 속성이 포함되어 있습니다.

속성	설명
`BatchSize`	각 배치 에 업로드할 청크의 수입니다. 기본값 은 16 MB를 `ChunkSizeBytes` 속성 값으로 나눈 값입니다. 데이터 유형: `int?`
`ChunkSizeBytes`	마지막 청크(더 작은 청크)를 제외한 각 청크 의 크기입니다. 기본값 은 255 KB입니다. 데이터 유형: `int?`
`Metadata`	다음 요소를 포함하여 파일 과 함께 저장 메타데이터입니다. 파일의 `_id`입니다. 파일 이름 파일 의 길이와 크기 업로드 날짜 및 시간 다른 정보를 저장 수 있는 `metadata` 문서 입니다. 기본값은 `null`입니다. 데이터 유형: BsonDocument

다음 예시 에서는 이전 예시 와 동일한 단계를 수행하지만 ChunkSizeBytes 옵션을 사용하여 각 청크 의 크기를 지정하기도 합니다. Synchronous 또는 Asynchronous 탭 을 선택하여 해당 코드를 확인합니다.

var options = new GridFSUploadOptions
{
    ChunkSizeBytes = 1048576 // 1 MB
};
using (var uploader = bucket.OpenUploadStream("my_file", options))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    uploader.Write(bytes, 0, bytes.Length);
    uploader.Close();
}

var options = new GridFSUploadOptions
{
    ChunkSizeBytes = 1048576 // 1 MB
};
using (var uploader = await bucket.OpenUploadStreamAsync("my_file", options))
{
    // ASCII for "HelloWorld"
    byte[] bytes = { 72, 101, 108, 108, 111, 87, 111, 114, 108, 100 };
    await uploader.WriteAsync(bytes, 0, bytes.Length);
    await uploader.CloseAsync();
}

기존 스트림 업로드

UploadFromStream() 또는 UploadFromStreamAsync() 메서드를 사용하여 스트림 의 콘텐츠를 새 GridFS 파일 에 업로드합니다. 이러한 메서드는 다음 매개변수를 허용합니다.

Parameter	설명
`filename`	업로드할 파일 의 이름입니다. 데이터 유형: `string`
`source`	파일 내용을 읽을 스트림 입니다. 데이터유형: Stream
`options`	선택사항. 업로드 스트림 의 구성을 지정하는 클래스의 인스턴스 입니다. 기본값 은 `GridFSUploadOptions` `null` 입니다. 데이터 유형: GridFSUploadOptions
`cancellationToken`	선택 사항. 작업을 취소하는 데 사용할 수 있는 토큰입니다. 데이터 유형: CancellationToken

이 코드 예시 에서는 다음 단계를 수행하여 업로드 스트림 을 여는 방법을 보여 줍니다.

바이너리 읽기 모드 에서 /path/to/input_file 에 있는 파일 을 스트림 으로 엽니다.
UploadFromStream() 메서드를 호출하여 스트림 의 내용을 "new_file"이라는 GridFS 파일 에 쓰기 (write) .

Synchronous 또는 Asynchronous 탭을 선택하여 해당 코드를 확인합니다.

using (var fileStream = new FileStream("/path/to/input_file", FileMode.Open, FileAccess.Read))
{
    bucket.UploadFromStream("new_file", fileStream);
}

using (var fileStream = new FileStream("/path/to/input_file", FileMode.Open, FileAccess.Read))
{
    await bucket.UploadFromStreamAsync("new_file", fileStream);
}

파일 다운로드

다음 방법을 사용하여 GridFS 버킷에서 파일을 다운로드 할 수 있습니다.

OpenDownloadStream() 또는 OpenDownloadStreamAsync(): 파일 내용을 읽을 수 있는 새 다운로드 스트림 을 엽니다.
DownloadToStream() 또는 DownloadToStreamAsync(): GridFS 파일 의 내용을 기존 스트림 에 씁니다.

다음 섹션에서는 이러한 메서드에 대해 자세히 설명합니다.

다운로드 스트림에서 읽기

OpenDownloadStream() 또는 OpenDownloadStreamAsync() 메서드를 사용하여 다운로드 스트림 을 만듭니다. 이러한 메서드는 다음 매개변수를 허용합니다.

Parameter	설명
`id`	다운로드 할 파일 의 `_id` 값입니다. 데이터 유형: BsonValue
`options`	선택사항. 다운로드 스트림 의 구성을 지정하는 클래스의 인스턴스 입니다. 기본값 은 `GridFSDownloadOptions` `null` 입니다. 데이터 유형: GridFSDownloadOptions
`cancellationToken`	선택 사항. 작업을 취소하는 데 사용할 수 있는 토큰입니다. 데이터 유형: CancellationToken

다음 코드 예시 에서는 다음 단계를 수행하여 다운로드 스트림 을 여는 방법을 보여 줍니다.

이름이 "new_file"인 GridFS 파일 의 _id 값을 검색합니다.
OpenDownloadStream() 메서드를 호출하고 _id 값을 전달하여 파일 을 읽기 가능한 GridFS 스트림 으로 엽니다.
파일 내용을 저장 buffer 벡터를 만듭니다.
Read() 메서드를 호출하여 downloader 스트림 에서 벡터로 파일 내용을 읽습니다.

Synchronous 또는 Asynchronous 탭을 선택하여 해당 코드를 확인합니다.

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    using (var downloader = bucket.OpenDownloadStream(doc.Id))
    {
        var buffer = new byte[downloader.Length];
        downloader.Read(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    using (var downloader = await bucket.OpenDownloadStreamAsync(doc.Id))
    {
        var buffer = new byte[downloader.Length];
        await downloader.ReadAsync(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

다운로드 스트림 구성을 사용자 지정하려면 GridFSDownloadOptions 클래스의 인스턴스 를 OpenDownloadStream() 메서드에 전달합니다. GridFSDownloadOptions 클래스에는 다음 속성 이 포함되어 있습니다.

속성	설명
`Seekable`	스트림 이 스트림 의 현재 위치를 쿼리 하고 변경하는 기능 검색을 지원하는지 여부를 나타냅니다. 기본값 은 입니다.`false` 데이터 유형: `bool?`

다음 예시 에서는 앞의 예시 와 동일한 단계를 수행하지만 Seekable 옵션을 true 로 설정하여 스트림 을 검색 가능하도록 지정합니다.

Synchronous 또는 Asynchronous 탭을 선택하여 해당 코드를 확인합니다.

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    var options = new GridFSDownloadOptions
    {
        Seekable = true
    };
    using (var downloader = bucket.OpenDownloadStream(id, options))
    {
        var buffer = new byte[downloader.Length];
        downloader.Read(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    var options = new GridFSDownloadOptions
    {
        Seekable = true
    };
    using (var downloader = await bucket.OpenDownloadStreamAsync(doc.Id, options))
    {
        var buffer = new byte[downloader.Length];
        await downloader.ReadAsync(buffer, 0, buffer.Length);
        // Process the buffer as needed
    }
}

기존 스트림에 다운로드

DownloadToStream() 또는 DownloadToStreamAsync() 메서드를 사용하여 GridFS 파일 의 콘텐츠를 기존 스트림 에 다운로드 합니다. 이러한 메서드는 다음 매개변수를 허용합니다.

Parameter	설명
`id`	다운로드 할 파일 의 `_id` 값입니다. 데이터 유형: BsonValue
`destination`	.NET/ C# 드라이버 가 GridFS 파일 을 다운로드하는 스트림 입니다. 이 속성의 값은 `Stream` 클래스를 구현하는 객체 여야 합니다. 데이터유형: Stream
`options`	선택사항. 다운로드 스트림 의 구성을 지정하는 클래스의 인스턴스 입니다. 기본값 은 `GridFSDownloadOptions` `null` 입니다. 데이터 유형: GridFSDownloadOptions
`cancellationToken`	선택 사항. 작업을 취소하는 데 사용할 수 있는 토큰입니다. 데이터 유형: CancellationToken

다음 코드 예시 에서는 다음 작업을 수행하여 기존 스트림 에 다운로드 하는 방법을 보여 줍니다.

바이너리 쓰기 (write) 모드 에서 /path/to/output_file 에 있는 파일 을 스트림 으로 엽니다.
이름이 "new_file"인 GridFS 파일 의 _id 값을 검색합니다.
DownloadToStream() 메서드를 호출하고 _id 값을 전달하여 "new_file" 의 콘텐츠를 스트림 에 다운로드 합니다.

Synchronous 또는 Asynchronous 탭을 선택하여 해당 코드를 확인합니다.

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    using (var outputFile = new FileStream("/path/to/output_file", FileMode.Create, FileAccess.Write))
    {
        bucket.DownloadToStream(doc.Id, outputFile);
    }
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    using (var outputFile = new FileStream("/path/to/output_file", FileMode.Create, FileAccess.Write))
    {
        await bucket.DownloadToStreamAsync(doc.Id, outputFile);
    }
}

파일 찾기

GridFS 버킷에서 파일을 찾으려면 GridFSBucket 인스턴스 에서 Find() 또는 FindAsync() 메서드를 호출합니다. 이러한 메서드는 다음 매개변수를 허용합니다.

Parameter	설명
`filter`	`files` 컬렉션 에서 일치시킬 항목을 지정하는 쿼리 필터하다 입니다. 데이터 유형: `FilterDefinition<GridFSFileInfo>`. 자세한 내용은 Find() 메서드에 대한 API 설명서를 참조하세요.
`source`	파일 내용을 읽을 스트림 입니다. 데이터유형: Stream
`options`	선택 사항. 찾기 작업에 대한 구성을지정하는 클래스의 인스턴스 입니다. 기본값 은 `GridFSFindOptions` `null` 입니다. 데이터 유형: GridFSFindOptions
`cancellationToken`	선택 사항. 작업을 취소하는 데 사용할 수 있는 토큰입니다. 데이터 유형: CancellationToken

다음 코드 Find() 예시 는 GridFS 버킷의 파일에서 파일 메타데이터 를 조회 하고 인쇄하는 방법을 보여줍니다. 메서드는 IAsyncCursor<GridFSFileInfo> 결과에 액세스 할 수 있는 인스턴스 를 반환합니다. 루프를 사용하여 반환된 커서 를 반복하고 foreach 파일 업로드 예제에서 업로드된 파일의 내용을 표시합니다.

Synchronous 또는 Asynchronous 탭을 선택하여 해당 코드를 확인합니다.

var filter = Builders<GridFSFileInfo>.Filter.Empty;
var files = bucket.Find(filter);
foreach (var file in files.ToEnumerable())
{
    Console.WriteLine(file.ToJson());
}

{ "_id" : { "$oid" : "..." }, "length" : 13, "chunkSize" : 261120, "uploadDate" :
{ "$date" : ... }, "filename" : "new_file" }
{ "_id" : { "$oid" : "..." }, "length" : 50, "chunkSize" : 1048576, "uploadDate" :
{ "$date" : ... }, "filename" : "my_file" }

var filter = Builders<GridFSFileInfo>.Filter.Empty;
var files = await bucket.FindAsync(filter);
await files.ForEachAsync(file => Console.Out.WriteLineAsync(file.ToJson()))

{ "_id" : { "$oid" : "..." }, "length" : 13, "chunkSize" : 261120, "uploadDate" :
{ "$date" : ... }, "filename" : "new_file" }
{ "_id" : { "$oid" : "..." }, "length" : 50, "chunkSize" : 1048576, "uploadDate" :
{ "$date" : ... }, "filename" : "my_file" }

찾기 작업을 사용자 지정하려면 GridFSFindOptions 클래스의 인스턴스 를 Find() 또는 FindAsync() 메서드에 전달합니다. GridFSFindOptions 클래스에는 다음과 같은 속성이 포함되어 있습니다.

속성	설명
`Sort`	결과의 정렬 순서입니다. 정렬 순서를 지정하지 않으면 메서드는 삽입된 순서대로 결과를 반환합니다. 데이터 유형: `SortDefinition<GridFSFileInfo>`. 자세한 내용은 정렬 속성 에 대한 API 설명서를 참조하세요.

파일 삭제

GridFS 버킷에서 파일을 삭제 하려면 GridFSBucket 인스턴스 에서 Delete() 또는 DeleteAsync() 메서드를 호출합니다. 이 메서드는 파일의 메타데이터 컬렉션 과 관련 청크를 버킷에서 제거합니다.

Delete 및 DeleteAsync() 메서드는 다음 매개변수를 허용합니다.

Parameter	설명
`id`	삭제할 파일의 `_id` 입니다. 데이터 유형: BsonValue
`cancellationToken`	선택 사항. 작업을 취소하는 데 사용할 수 있는 토큰입니다. 데이터 유형: CancellationToken

다음 코드 예시 에서는 _id 값을 delete_file()에 전달하여 이름이 "my_file" 인 파일 을 삭제 하는 방법을 보여 줍니다.

Builders 클래스를 사용하여 "my_file"이라는 파일 과 일치하는 필터하다 를 만듭니다.
Find() 메서드를 사용하여 "my_file"(이)라는 파일 을 찾습니다.
파일 의 _id 값을 Delete() 메서드에 전달하여 파일 을 삭제 합니다.

Synchronous 또는 Asynchronous 탭을 선택하여 해당 코드를 확인합니다.

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var doc = bucket.Find(filter).FirstOrDefault();
if (doc != null)
{
    bucket.Delete(doc.Id);
}

var filter = Builders<GridFSFileInfo>.Filter.Eq(x => x.Filename, "new_file");
var cursor = await bucket.FindAsync(filter);
var fileInfoList = await cursor.ToListAsync();
var doc = fileInfoList.FirstOrDefault();
if (doc != null)
{
    await bucket.DeleteAsync(doc.Id);
}

참고

파일 수정본

Delete() 및 DeleteAsync() 메서드는 한 번에 하나의 파일 삭제만 지원 합니다. 각 파일 수정본을 삭제 하거나 동일한 파일 이름을 주식 하는 업로드 시간이 다른 파일을 삭제하려면 각 수정본의 _id 값을 수집합니다. 그런 다음 Delete() 또는 DeleteAsync() 메서드에 대한 개별 호출로 각 _id 값을 전달합니다.

API 문서

이 페이지에서 사용되는 클래스에 학습 보려면 다음 API 설명서를 참조하세요.

이 페이지에서 사용된 GridFSBucket 클래스의 메서드에 학습 보려면 다음 API 설명서를 참조하세요.

돌아가기

지리공간적 검색

복제본 세트 작업